Writing Better Design Documents

21 Jul

Design documents are a tricky thing, and can vary in purpose and form depending on the developer.  For some (Naughty Dog comes to mind) the design document is short and to the point — the rest is left up to team cooperation throughout development.  For others still the design document is a modular ‘wiki’; appointed wiki masters manage submissions and revisions by team members, and the document is constantly kept up to date.  And for some, sadly, the design document is just literal documentation; a detailed description of ‘the plan’ that nobody reads and is there to comfort executives.

All of the following best practices are more or less extracted from Damion Schubert’s latest presentation on writing design documents, and from my own experience and schooling.  You can find the presentation here.

Hit the jump for a delicious wall of text.

——————————–Overview ——————————–

What will be covered:

Getting Started



The Process

Scrum and Design Documents


The most important point to make is that as a designer, you will always be learning how to write a good design document.  Different studios and different games call for different requirements, and so standardization is difficult, and can even be damaging (ie. formulaic games would be produced).

Another excellent point Schubert establishes early on is that common complaints about design documentation are more or less tied to how you, or the designers that team has worked with in the past, have constructed their documents.  If someone is telling you that design documents are a waste of time, it’s because they’ve been exposed to poorly constructed documents.  Hopefully they weren’t yours.

Important to note is the distinction between a Systems Design Document and other overview-type documents.  That alone should be something you actively think about while formatting your document: you are detailing how a system functions, and in doing so how it will be built.  A system is a number of things coming together to form something complex; make sure the document supports that cohesion.  Documents I have written personally tend to have story sections to keep team members on the same page thematically, but I admit it would be better to contain that in its own document and reserve the actual design document for detailing the game system.

——————————–Getting Started——————————–

Don’t start creating the document in isolation.  Even if you are ‘the doc guy’ your skills are being exemplified by how usable, concise, and detailed the documentation is — it does not mean you alone are designing the game.  This is a more applicable warning to students than professionals, as it can be easy to start thinking you are the one responsible for writing the document in isolation.

Decide on the goals of the game systems so the document has a clear beginning and ending in terms of what it details.  Schubert notes that a design document could probably go on forever, since different systems will inevitably touch and influence each other.  That much detail should be avoided, as it’s not particularly useful but can clutter the document and confuse everyone.

And of course, look at games that are similar to yours and see what you can borrow or use as a guideline.  If your game is a shooter, you’re hurting yourself by not looking at what the best shooters are doing; see how they did something and then determine how you are going to do it or what you will be changing.

Brainstorm, etc.

Now, this is especially vital if your intention is to create a true ‘living document’ that is going to play nice with an iterative design process: the design document should start out simple, outlining what is essentially a prototype of the intended final product.  Test that build, get feedback, then iterate and expand the complexity of the document.  This is the major failing of any sort of document writing class — you can teach anyone to construct a document that can be used as a blueprint to construct their dream game, but you can’t teach iterative development and the documentation that entails outside of making a game.  So in practice, build the complexity of the system as the actual game build grows.

Think of cellular automata; complex things are defined by simple instructions that multiply to create complexity.  Creating complexity from the outset — creating a blueprint — is going to hurt this process, doesn’t make sense for iterative development, and is sadly what I was taught at first.

And remember, the programmers are the ones building the game system you’re writing.  Make friends with them.  Ask them what they want and need from the document.

And lastly, ‘kill your babies’.  It’s rare for a design to maintain itself in its entirety through an iterative development cycle, so be prepared to see your favourite little features mutate or dissapear.  And, just like any sort of writing, if you aren’t prepared to let someone read your document, then you know there is something wrong with it and “it is probably either too complex or too weird”.


Fewer pages are better than more pages.  A big document is not the goal here.  The longer the document is, the more ends of different systems meet, and the more contradictory your document will become.  Or, it just means you’re not being concise enough.  Be concise.

Schubert has some great examples of the following starting on slide 26 of his presentation:

Create modular sections in your document.  If you have a section that contains all of the enemies in your game and another section that contains all of the weapons, keep them separate.  When describing an enemy and the weapon he uses, do not copy and paste from the weapon section, reference back to it with a hyperlink.  Basically, try not to copy and paste information, be referential.

Break things up into phases and prioritize.  What does this mean?  Firstly, it does not mean ‘describe what you can do conservatively, then describe what you could do with more time’.  Outline what functionality a feature needs to have for the prototype build; what functionality it needs to work correctly; what functionality it needs to have when the game ships; what could be done post-launch (patch, DLC, etc); and what could be done if you had tonnes of money or extra time.  The important thing to take away here is that something might get cut due to costs/development time, and you need to be able to point and say ‘this won’t work if it’s not at this level’.

Illustration.  This doesn’t mean you have to include pictures everywhere, but pictures help.  For example, screenshots of similar games so that people can get a feel for what you’re shooting for.  Diagrams and flowcharts can accomplish this as well, in different situations.  But most importantly, remember that you can illustrate something with text, Schubert calls it ‘example text’.  If you feel that a piece of technical writing requires a summation of some kind you can write a short blurb from the user’s perspective: walk the reader through what someone would do if they spent a minute with your inventory system, etc.

Don’t tell others how to do their jobs.  This comes into effect with user interfaces that are going to be displaying some of the functionality or user feedback of the game system.  Schubert’s point here is likened to how humans perceive abstract representations as compared to a realistically rendered representation.  If someone sees a rudimentary smiley face they’re going to project their own viewpoint onto it: basically, if you tell someone how to do something then you’ve stunted their creative process.  This is a bit tricky since everyone works differently.  For instance, when I design a user interface I’ll often tie the art style to the functionality: if the interface is supposed to be a dirty martian control panel, then I’m going to go into Photoshop and create a control panel.  I don’t see anything wrong with this as long as you make sure you’re not stepping on anyone’s toes.  In such an instance, talk to the artist who will be working on the UI before you go ahead with it.  Make sure he understands why your dirty designer art exists on the wireframe mockup, and that he is to use it only as a springboard for his own artwork to complement the functionality.

So, if you can, describe the functionality and let the artist interpet the aesthetic qualities that should work with it.

Capture your reasoning.  Again, build your document to be modular and compartmentalize things.  State things rather than explain things.  If anyone needs an explanation, direct them to a Frequently Asked Questions section.


Form, as in external appearance.  Humans are visual creatures, and generalities that you might not consider will have an effect on them.

For instance, you’ll find on slides 46 and 47 of Schubert’s presentation that he speaks about separating code from content.  When he says code he is talking about functionality: what do the programmers need to do, what are the code requirements to make that feature work.  He takes a large bullet point list and distills it into two levels of functionality — basic and advanced — written in text, with the corresponding content that that functionality requires boxed up in a neat little chart underneath.  Programmers are going to be able to dechiper what work they need to do out of that much better than they would with a bullet point list.

Make sure navigation is easy. If your document has been designed modularly this is no problem.  Include a table of contents.

Find a format and be persistent, but don’t be afraid to break it.  People like things that look ‘professional’, and trust it more.

Be clear.  If you’re going to be using jargon, don’t even assume that everyone reading your document will know what it means. Establish its meaning clearly if you must use it, but try to simplify terms.  Schubert even suggests including a glossary.

Back to being referential.  Don’t let your document be redundant, as it can cause problems when updating.  For instance, don’t copy and paste information from another document as you then have to update two instances later (and may make a mistake or miss updating something), but rather reference the other document with a link.

No weak language. The use of phases and prioritizing should eliminate the use of words like “if, when, maybe, perhaps” etc.  Speak in absolutes.  A system is designed, and a design is concrete.  It may change later, but at the moment of writing that does not matter.

——————————–The Process——————————–

Writing a game design document is not something to be practiced in isolation, so make sure you establish what you need in that first meeting.  What are the team goals for the project, what are the boundaries the team will be working within — how expansive and involved is this game system.

Using phases, concentrate on the phase at hand.  Don’t concern yourself too much with the next phase of functionality.  The requirements for the next phase could change when you’re done designing and locking down the current phase.

Consult slide 61 of Schubert’s presentation for how a design document can “survive contact with the enemy”.

Have an approval process for the design document.  Lead Designer –> Design Team –> Senior Leads/Cross-Team.

Establish a way to visually track the approval process.  Schubert reccommends, on slide 63, using post-it notes on a whiteboard or something similar.

Have a change process.  Things will change, so plan how you will handle those changes.  Have someone act as an arbiter, such as a lead designer, or leave it up to some sort of team approval — this really depends on the studio.  Valve’s change process is no doubt quite different from id’s change process.

Make it searchable — this ties back to choosing a wiki format.

Remember that this is a business and be ready for your producers to tell you what you can never show.

‘Audit’ the process.  Make sure the team is comfortable operating within the bounds you have established.

————————Scrum and Design Documents————————

Read slide 71 and on for Schubert’s more in-depth comparison.

He suggests concentrating your documentation on user storiesThese are short function requirements written in plain english.  This use of user stories is still more involved than how they generally function in other areas of software development, as Schubert creates a user story with one requirement, and several sub-requirements housed within it.

Keep in mind that when you are constructing a user story you are creating tangible work for coders.  You need to be able to estimate how much coding time your requirements are going to take — for one user story operating with Scrum, it needs to be under one week.  Schubert gives some guidelines on slide 74.


One Response to “Writing Better Design Documents”

  1. Dean Longmore January 9, 2009 at 2:50 am #

    A great read, I haven’t looked at the slides – but this seems like it’ll be a good companion.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: