Sponsored By

The Designer's Notebook: Why Design Documents Matter

Creating design documents may not be the most glamorous part of game design, but in this latest Designer's Notebook column, veteran designer Ernest Adams outlines the important role these reference tools play, while highlighting five key reasons developers should consider using design documents in their projects.

Ernest Adams, Blogger

July 17, 2007

14 Min Read

From time to time I get questions from students, or see postings on the Internet from newbie developers, demanding to know why they should write design documents. They want to dive straight in and get modeling or coding, and they see the paperwork as a waste of time. The player will never see it, so why take the trouble to write it?

I know the feeling; I was that way too, when I first started making games. I remember writing out FORTRAN code long before I had a clear idea of how my game was going to work either as a form of entertainment or even as a piece of software. Of course, back then there were no experienced designers around to tell me how it should be done - everybody made it up as they went along.

One of the most common newbie objections to writing design documents is that nobody reads them. That sounds valid at first, but it actually misses the point. Nobody reads the phone book, either, but if there weren’t a way to look up phone numbers, the telephone would be a lot less useful. Like the phone book, most design documents aren’t intended to be read but referred to. Nobody reads them cover to cover, but managers and developers look things up in them that are relevant to their particular tasks.

Another common objection is that, as most games are prototyped first, the prototype can form the basis for the game and the team can just keep adding new features to it, so why write a document? But that’s not what a prototype is for, and doing it robs the prototype of its value. They’re intended to be quick and dirty, and the dirtier they are, the quicker they can be. They’re testbeds, not designs - you can play them, but you can’t look up data or plans in them.

In Mark Cerny’s famous design methodology, he warns his developers that every scrap of material they create for a prototype will be thrown away. This frees them to cut corners as much as they like, secure in the knowledge that whatever kludges they make in the prototype, those kludges won’t find their way into the product. It’s always dangerous to try to turn prototype code into final code, and Cerny avoids those risks by making sure it doesn’t happen.

Also, prototypes almost never include all the content of the final game. We build prototypes mostly to test mechanics and user interfaces. If a game will have thirty levels, the prototype might implement three or four, or maybe only one. Somebody still has to design and document all the remainder for the content teams to construct them. A prototype can’t replace the documents - diagrams, maps, lists of objects and so on - that are needed to build those levels.

So far I’ve answered some objections, but I haven’t advanced any positive reasons why design documents matter. Anybody who’s led a big project in the mainstream industry knows perfectly well why they do, but it's still a reasonable question for those who haven’t enjoyed that dubious privilege. There are actually several reasons, which I’ll address from least to most important.

Reason 1 (least important): Funding agencies (publishers and others) want design documents as evidence that the designer knows what he’s doing.

A lot of people in the industry would like to get the money first and figure out the details later - heck, who wouldn’t, if you could get away with it? Sometimes you can sucker a private investor into letting you do that, especially if they don’t know much about the business. But a sensible publisher simply won’t hand over several million dollars to a designer who doesn’t have a clear plan in mind.

Executive producers want to see something in writing. They no longer insist on a 300-page game bible, as they did 15 years ago, but they still want something they can hold in their hands and take to show the marketing department. These days it's more likely to be a 30-page treatment, but it’s still a design document and somebody has to write it. No document, no money.

If you’re self-funded, this isn’t an issue, but there are several other good reasons for writing design documents even if you’re paying your own way.

Reason 2: Design documents are sometimes the basis for contractual obligations.

Most development contracts include a milestone schedule that dictates when the developer will produce certain deliverables and when the publisher will advance more development money. You can’t create a schedule until you know what features will be in the game, and you can’t know that until you’ve designed at least part of it, including some kind of a written record to build the schedule from.

In practice, milestone schedules always change, and the feature list almost always changes too. That doesn’t matter; you have to start somewhere. No feature list, no milestone schedule; no milestone schedule, no contract. Furthermore, it’s in the developer’s best interests to have each milestone deliverable be as clear and unambiguous as possible.

If the developers can demonstrate unequivocally that a certain amount of the work is done and a new payment is due, they are in a position of strength. If the game design consists of a lot of vague hand-waving, the publishers can do a lot of hand-waving in return when explaining why they are withholding payment and demanding more work. The more you know in advance about what you are promising to provide, the more confident you can be that you have met your obligations when the time comes.

In addition to the developer’s legal relationship with the publisher, there’s also the developer’s legal relationship with external content providers to consider. Music, art, animation, and writing are frequently outsourced to specialized agencies these days. In order for those companies to do their jobs, they have to have documents telling them what’s wanted, and again, those documents may form the basis of their contract.

Reason 3: Design documents communicate your intentions to the rest of the team, and let them plan their tasks.

In theory, this is why anybody writes a design document: to communicate information to others. Small teams don’t need this as much because the team members are often working in the same room and talking to each other all the time. This is why students and newbie independents don’t see the point of writing design documents: they assume that if they can all talk together, there’s no need to put anything on paper.

However, as we’ve seen, some documents are created for business or contractual reasons, and they serve other functions as well. Strangely enough, communicating with the rest of the team isn’t actually the most important reason for writing a design document. But it is one of the reasons, and a good one.

Instructors make students write design documents even though student teams don’t always require them for communication because the instructors know that the students won’t always be on a small team, and they need the practice before they get into the working world. Large dev teams can run up to 150 people, often spread out over several offices and even several countries, if some of the work is outsourced. Talking all the time, even on the phone or in videoconferences, is impractical.

Electronic Arts' long running Madden NFL series 

The bigger the game, the more important it is to document the design so that others can build their schedules. If you want your game to include 45 types of moving creatures, the artists will have to make models, textures, and animations for all of them. They’ll need concept art to work from - another form of design document. The audio engineers will have to find or create sound effects for each creature. If the creatures are autonomous, the programmers will have to know their behavioral characteristics. If you don’t write all this down, how will all those people know what to do? You can’t just explain it all in a meeting and expect them to remember it.

When I was doing the audio/video production for the Madden series, I wrote the audio recording scripts for the play-by-play - yet another form of design document. All told, they were about 75 pages long. We had to record material for every possible event that could occur in the game, and all of John Madden’s color commentary as well. Nobody could possibly keep all that in his head, and in any case, Madden needed something to read from in the voice booth, and the audio engineer needed something to work from when editing the raw recordings.

Sports games require more design docs than you might think, because even though the league has created the rules of the game, somebody has to figure out all the strategies (in football, the playbook for each team), animations, and user interface required to translate the sport to the target hardware. All that work produces documentation.

Finally, on some projects, not all the team members will speak the same language - literally. I encountered this when working with THQ (England) and GSC Game World (Ukraine) on S.T.A.L.K.E.R.: Shadow of Chernobyl. Most of the developers did not speak English at all, only Russian or Ukrainian. They couldn’t have simultaneous voice translators standing by 40 (or 60) hours a week, so a great deal of communication between the publisher and developer took place in the form of translated documents.

Reason 4: Design documents turn generalities into particulars.

The process of writing a document turns a vague idea into an explicit plan. It’s one thing to say “Harpies will be flying creatures” in a meeting, but that’s nowhere near enough to build from. In fact, there’s not even any point in writing it down if that’s all you have to say. What the developers need are details: How high can they fly? How fast do they fly? Are they affected by the weather? Can harpies land? Can they land anywhere they want to? Can they also move on the ground, and if so, what sorts of terrain and how fast? Are they more, or less, vulnerable when in the air or on the ground? And so on and so on, and it all needs to be written down so that everyone on the team has all the information they need to build the product.

It would be nice if game design consisted of sitting around with your feet up and daydreaming about cool content and features, and I’ve met some designers who thought that was the whole job. It isn’t; they were slackers. The vast majority of design consists of figuring out the details.

Although you’ll always change those details later in testing and tuning, you have to start with something. In a real sense, the process of writing documents is the process of design, because it is then that you turn abstract concepts into concrete plans. Even if no one reads your document at all, an idea written down is a decision made, a conclusion reached.

Reason 5 (most important): Design documents are a record of decisions made; they create a paper trail.

Video game design is a highly collaborative activity, far more so than the movies. Unlike a film director, whose rule is well-nigh absolute, few designers are allowed total control over their game. As developers, we tolerate the long hours and comparatively low pay of the game industry because we get to make a creative contribution, and if that were taken away, it wouldn’t be much fun. A lead designer does not create the entire design himself; he continuously weaves other people’s ideas into the whole, and must also (preferably with a degree of tact) reject those ideas that don’t fit.

As a result, an enormous number of design decisions are made not at your desk, but in meetings, around the coffee pot, or over lunch. Some of these, perhaps made by junior staff, are only tentative and must be cleared with the lead designer or the rest of the team. In any case, when a design decision occurs through conversation or negotiation, you must get your conclusions down in writing - again, even if you already know that you’ll change them later.

The reason is that you need a paper trail, a record of what you have decided. I have sat in too many meetings in which an argument broke out because nobody wrote down an earlier decision, and people’s memories of what was decided were in conflict. “Didn’t we say we were going to do X?” “No way, we were going to do Y!” The result is wasted time and energy. If a week or two has gone by since the previous meeting, a whole team may have spent all that time working based on an incorrect assumption.

THQ and GSC Game World's PC shooter S.T.A.L.K.E.R.: Shadow of Chernobyl

This is why all meetings should have a designated secretary or scribe to make notes and distribute them to interested parties - and where the questions discussed are design issues, these notes are part of the design documentation and should be filed as such. When people’s memories conflict, you can go back and check the notes.

Design docs also help you keep track of what you’ve done and what you still have left to do. If a feature of your game is never described in writing, there is a good chance that you overlooked it and that someone will have to come and ask you about it later, or worse, make up her own answer without consulting you or anyone else. The result can be a disaster, when each part of the team has a different idea of what you intended, and they build incoherent or incompatible material. It’s far easier and cheaper to correct a design error before any code is written or artwork is created.

I listed this reason as most important because above all, design documents are organizational tools. They’re not books or stories to read, but plans: records of things to implement. They can take many forms: diagrams, concept art, graphical reference material, explanatory text, tables of stats or attributes, lists of many kinds, storyboards, flowcharts (yes, even today, but for command sequences in a user interface, not for the code), meeting notes, audio and video recording scripts, and pitch documents to help sell the product to the funding agencies.

When the game is mostly complete and the majority of the work consists of testing and tuning, you can throw the design documents away just as a builder takes down scaffolding - though it’s still useful to keep them around for reference. But while things are in flux, design documents are essential for keeping track of what’s going on and what needs to happen next.


Design documents alone won’t guarantee that you’ll make a great game or even a good one, nor that you’ll get done on time. In fact, when approached wrongly, a design team can waste a lot of valuable time and effort on their docs, and I’ll address some of those pitfalls in a future column. But I hope I’ve answered some of the questions I hear from the innocent and the ignorant.

Yes, a small team working on a small game, perhaps with no deadline to meet, doesn’t need much in the way of design documentation. If your entire design career will be devoted to trivia games on mobile phones, you may never create one (but somebody has to write down the trivia questions, don’t they?). Nevertheless, serious professionals working on a large project that’s due out at Christmas understand the value of documentation. It communicates, organizes, and guides the entire process. A project manager can’t create a schedule, task list and staffing allocation - and follow their progress - without knowing exactly what needs to be built, and that information must exist in written form.

Ultimately, writing (and sketching, and diagramming, and making tables and lists, and writing pseudo-code) is design. You shirk it at your peril.

Read more about:


About the Author(s)

Ernest Adams


Ernest Adams is a freelance game designer, writer, and lecturer, and a member of the International Hobo game design consortium. He is the author of two books, Andrew Rollings and Ernest Adams on Game Design, with Andrew Rollings; and Break Into the Game Industry: How to Get a Job Making Video Games. Ernest was most recently employed as a lead designer at Bullfrog Productions, and for several years before that he was the audio/video producer on the Madden NFL Football product line. He has developed on-line, computer, and console games for everything from the IBM 360 mainframe to the Playstation 2. He was a founder of the International Game Developers' Association, and a frequent lecturer at the Game Developers' Conference. Ernest would be happy to receive E-mail about his columns at [email protected], and you may visit his professional web site at http://www.designersnotebook.com. The views in this column are strictly his own.

Daily news, dev blogs, and stories from Game Developer straight to your inbox

You May Also Like