Tips on Writing Design Docs
Posted by Raphael
I get a lot of emails asking about how to write design documents, so I thought I'd write up some short bullets here to cover the questions that seem to come up most regularly. Hopefully they are helpful, and if you have specific questions that aren't covered here, please don't hesitate to ask!
I've written a fair few design docs, and have had to decipher many more, so although there are people out there much more qualified to provide direction, I have some ideas based on my own experience -- take them if they're useful, ignore them if they're not.
Tips for Writing Design Docs
It's become common wisdom over the past several years that writing monolithic game design docs is really a thing of the past. With projects being as vast and complex as they are today, and teams being as large and as multi-disciplinary as they are, the notion that an individual, or a small group of people, can design an entire game on paper and have that documentation be relevant is...kind of silly.
But, equally silly is the notion that design docs are a complete waste of time and have no place in today's modern development environment. Documentation is very useful, very important, and if nothing else a critical part of the concept development process.
That said, there are probably a few 'best practices' that, if kept in mind, will help you ensure your documentation is of the useful variety.
Tips for Writing Design Docs
- Keep them short and sweet, but without sacrificing necessary detail. Being succinct isn't useful if the reader doesn't find the information they're looking for. So, focus on being thorough but avoid unnecessary detail.
- Focus on function. If you're a designer, it's probably not your job to go into incredible detail about how a particular UI element should look, or what an audio cue should sound like. You need to identify the function of the feature and describe what it does and how you as a designer need to be able to use it, including what elements of 'tunability' are inherent in the feature. Then, you let the experts in other fields weigh in on the supporting elements that help manifest the design feature into content the player experiences in the game.
- Rely on formatting. Proper formatting can do wonders to help communicate important elements of your design. Don't be afraid to use the *full range* of text formatting tools available to you in any decent word processor or online documentation tool (wiki, Basecamp, etc.). Yes, that includes indentation, colour, and even underlining! Don't be shy about using tables or charts, add imagery if it helps. Once you've written and iterated on several designs, in collaboration with the people who will work with you to implement the systems, you'll have a good idea of the type of information people need, and the best way to present it. Build a template and use it consistently, incorporating the best elements of other people's design documents into it, until you have a robust template that your entire design team can use. Consistency in documentation is of paramount importance, especially when you have many design clients and they need to be able to find information quickly, which leads us to...
- Know your audience. Are you writing your doc (I prefer to call them 'specs' myself, since they are meant to be the design specifications of a feature, not a document per se) for other designers? For your design lead? For an artist? A programmer? Internal stakeholders or external publisher people? All of the above? You need to know your audience in order for your documents to be effective. Write in clear language using common terms, and if you introduce new terminology remember to note the terms in a glossary, and make sure you use them consistently (and that other people use them consistently as well -- I can't tell you how many cycles I've burned trying to sort out confusion over inconsistent use of terminology...it's the enemy of clear decision-making!).
- State the intent. State the intent of your design right away. It gives immediate context, helps calibrate the reader, and puts them in the proper frame of mind to internalize the information you're about to deliver to them in the rest of your spec. Stating the intent first is also a very good way to find out if you're really ready to write your spec; if you can't outline the intent of the system you are documenting in a few short, concise sentences using clear language, then you may not actually be ready to write about it. Take the time to understand it fully in your mind before you go too far in your documentation. It's a common fallacy that writing design docs is the same as designing features. Do your design work up front, and use the documentation process to make sure your ideas are as bulletproof as possible.
- Layer your information. If some perpetually harried lead only has a few minutes to review your design, what do they need to understand and retain about it after they've moved on to the next thing? Present your information in layers, beginning with the basic foundational knowledge that is critical to understanding the spec, and add increasing layers of detail as you progress. It's a common documentation 'truth' that you should never use a new word or mention a new concept before you've had an opportunity to introduce it to your reader properly, so be organized about how you present your information so that you've built up the conceptual framework before you expect people to start building on top of it.
- Remember that information is personal. Or at least, the way we present it is. I'm a huge believer in the value of using white-boards and/or mindmapping software to brainstorm ideas (not just for design, but for story developing, and even project planning), but you need to remember that 100 people using mindmaps to design the same feature will come up with 100 different mindmaps that really only make sense to them. The information came out of your mind, wholesale and unfiltered. It's not supposed to make sense to anyone but you! So don't expect you'll be able to simply pass it on to someone else and they'll immediately grok the brilliance of your system. For me, mindmappers and whiteboards are simply a tool -- a hugely indispensable tool -- but a tool just the same. The map is not the territory, so try to remember that. If you can take the results of your mindmapping adventures and translate them into coherent documentation that follows some established 'best practices' (as they exist for your studio or team) and even use documentation templates, then you're way ahead of the game.
Well, that's all I can think of for the moment. If any other useful tips or 'best practices' come to mind, I'll be sure to update this post. In the mean time, feel free to shout out if you found this useful, and request any clarifications or updates you'd find helpful.
0
comments »
Posts
