A version of this article first appeared in the December 2008 issue of Game Developer magazine.

It’s always astonishing to see the vast disparity in standards in game design documentation.  Every team and company seems to have their own ideas of how to present their ideas.   I’ve also seen hundreds of sample design documents from dozens of would-be designers when they submit them as work samples along with their resumes.

All these documents seem to have at least one thing in common, though.  Most game design documents I’ve seen really stink.

The lack of standards in writing good game design documentation has resulted in most designers and design teams shooting from the hip, throwing everything but the kitchen sink into a game design document, and then being flabbergasted when programmers choose not to read them.

Here’s a hint: if programmers are asking you to rewrite your 10 page design document into a half-page of bullet points – and you can – your design document presentation probably has room for improvement.  So what makes a good game design document?  Here’s a hint: what did your programmer just ask you to do?

Consider the audience

The most important thing to remember for any document is to consider the audience that it is written for.  Design documents for game systems are usually written for multiple audiences: other designers to get design consensus, producers and project managers for scheduling, QA for building test plans, and programmers for actually building the thing.

While the other audiences are important , the most important goal of a design document is to ensure that the design is communicated clearly, and the feature is developed to spec.  And as a result, a good place to start is to actually ask your coders to evaluate your design documents, and ask them if there is a way that you could make these documents more effective.

Sometimes, getting the answer to this is like pulling teeth, but when I ask the question, I typically get the same three requests: keep it short, keep it up-to-date, and preferably deliver it in a bullet point list.  Simple.

And now, paradoxically, I’m going to spread this into a two page article.

Keep It Short

The most common mistake I see in game design documentation is that most of them are way too long, and way too in-depth.  Too many designers try to write books, thinking that every word is important.  We are, as tradesmen, too often in love with the sounds of our own voices.

Who cares about the history of the weapon factory that devised the Huge Honking Gun?  Who wants to know why the Gods had decided to allow players to unlearn all the boxes in their skill tree?  Most programmers I know have better things to than read all that piffle.  Such as, say, code the game.

And let’s not forget: shorter design documents are easier to write and maintain.  It’s always faster to write a concise two-pager than a 30 page design bible – and faster and more accurate to incorporate changes as the design shifts throughout the creative process.

Longer doesn’t necessarily mean better.  The Gettysburg Address was only 256 words long.  The U.S. Declaration of Independence: 1337.  Both seemed to do a pretty good job of getting their point across.

Keep it Relevant

I was once being interviewed by a creative director when, midsentence, another designer literally wheeled in a few copies of the design document.  On a trolley.  The design document was more than a foot thick, and required multiple binders for a single edition.

These design documents are almost always doomed.  I know of another studio that referred to a similar tome as the ‘Big Book of Stupid’.  It had been written in preproduction, but was so huge and unwieldy that the programmers never referred to it, which resulted ultimately in nobody taking the document seriously.  Attempts to refer programmers to the document resulted in responses akin to, “Yeah, whatever, what do I really need to do?”

Needless to say, the final game looked nothing like the design document.

Design documents that are too long and too detailed are almost impossible to keep accurate and up-to-date.  As this happens, the documents lose their credibility, which results in them being used less, which ultimately ends up in design documentation largely being a huge time sink that most projects cannot afford.

Learn What Needs No Explanation

Yes, your guild system may require 6 different confirmation boxes, but each of those confirmation boxes does not require its own GUI mockup and page-long explanation of what each button does.  It can even cloud the issue –  if five of the dialogs are identical but one is crucially different, you run the risk that that difference will be lost to an implementer not reading carefully.

Don’t skimp on your design documents: if you care about a detail that’s different, include it.  But at the same token, don’t document features that are obvious or trivial.  We KNOW that the little X in the corner of the GUI will close it.

Don’t try to solve problems that aren’t yours to solve, such as how much memory needs to be reserved for quest variables.  Tell the coders, as simply as you can,  what the end user requirements are (“the player needs to have 25 quests at a time, and may complete 5000 quests in his lifetime that can’t be repeated”).  Don’t forget, programmers LIKE solving problems, and when it comes to nitty gritty technical issues, they’re probably better at it than you are anyway.

And don’t cut and paste from other documents. Doing so is a good way to ensure that one of the two docs will go out of date as your design shifts via iteration.  If another document has crucial information to help people understand your system, link it instead.

Illustrate

A picture is worth a thousand words, and nobody likes reading design documents anyway.  It’s on you, the designer, to find the simplest, most concise way to communicate your system to others.  Consider any possible avenue:  Visio diagrams, video clips from other movies and games, mocked up screenshots, excel graphs.  Visual aids can often get the point across the user much more quickly and effectively than text.  All also are much easier to discuss freely in a meeting with implementers or other designers.

And sometimes, text is the best way to illustrate.  Writing a short piece of prose can help make complex system interactions more clear, and can also help to make the feature more exciting.  But use this sparingly: Anytime you ‘sex up’ a document with whiz-bang descriptions of coolness, ask yourself if you are making it harder for programmers to find their task list.  I’ve found the most effective way to use such textual illustrations is in clearly defined callout boxes.  This allows programmers to safely ignore the prose while they complete the feature.

Plan for Iteration

When tasked to spec out a new system, most designers over-design.  They build fantasy land wish lists with every possible bell, whistle, and kitchen sink that they can think of, and throw it into the design document – just in case.  This approach is usually flawed on two fronts.  The first is that you never have time to do everything you want to do, and those features just end up bloating the document, making the feature seem bigger and harder to code.  The second, and far more crucial, is that once the feature is partially coded and suddenly tangible, other, more crucial and obvious improvements and fixes become clear.

Don’t cut those ideas, but plan for the iteration.  Mark core ideas that must be completed no matter what at the front of the document, and give them all necessary detail.  Put less crucial or well-formed ideas in an appendix near the end, clearly marked as a place where design iteration could lead.  Don’t spend too much time designing for these features that are likely to be cut.  And don’t get emotionally involved with any idea that is way down on the horizon.

The Political Implications

Designers, you are not being paid by the word.  More painfully, the opposite is true: there are severe political ramifications for design documentation that is too long and too in-depth.  Big design documents feel like big features that take a big time investment.  I have literally seen programmers call a feature a six-month feature simply by feeling the heft of the document.  I’ve also seen projects get doomed because the sum of all their design documentation made the project an insurmountable mountain that could never be completed.

The opposite is true: lead designers and producers have very limited budgets and usually intractable time restraints to work within.  Proposing a wacky system?  If you’re a lead and you have limited resources, what are you going to be drawn towards: the simple system described in a two-page document (counting illustrations!), or the 30 page manifesto, complete with pompous backstory, nonsensical design theory, and unworkable crack?

Ideas are cheap in this industry.  What separates good designers from the bad are the ability to get those ideas made, and then make those ideas fun.  It’s not enough to have a great idea – you have to figure out how to communicate it as well.  Design small systems, plan for iteration, and identify places for expansion.

The best way to make this happen will vary from team to team, and project to project.  But when in doubt, try brevity.