Sponsored By

Game Design: Theory & Practice Second Edition: 'Not All Game Design Documents Are Created Equal'

In an exclusive excerpt from Richard Rouse's revised, expanded "Game Design: Theory & Practice" book, the author argues that "many of the [design] documents that have been used for published games... are truly terrible", exploring issues and solutions for those creating game design 'bibles'.

November 1, 2004

23 Min Read

Author: by Richard Rouse III

The following excerpt comes from Richard Rouse III's book Game Design: Theory & Practice, which has just been released in a revised and expanded second edition. The book covers all aspects of game design, from coming up with a solid idea, through implementing the gameplay, to playtesting the final game. Along the way, before coding begins, a game's design typically takes the form of the infamous design document. But, as Rouse discusses in this excerpt from ‘Chapter 19: The Design Document’, not all game design documents were created equal.

"Omit needless words. Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid all detail and treat his subjects only in outline, but that every word should tell."

- William Strunk in his book The Elements of Style

Inauspicious Design Documents

As I previously recommended, it may be useful to try to get your hands on some professional game design documents in order to give you an idea of what the industry expects in such specifications. However, you must be careful. It is likely that the document you obtain will not be any good. Many of the documents that have been used for published games and that were written by experienced professionals are truly terrible. By way of example, and in order to best teach you what to avoid, I will explore a few of the different types of horrible design documents, and why they fail so miserably at what they are supposed to accomplish.

The Wafer-Thin or Ellipsis Special Document

These thin little volumes, certainly none longer than thirty pages, startle and amaze the experienced game designer with their total and complete lack of any useful content whatsoever. They use meaningless descriptions like “gameplay will be fun” and “responsiveness will be sharp.” In these documents, many comparisons to other games are made: “This plays like Super Mario 64” or “The game has a control scheme similar to Quake.” While such comparisons can be slightly useful, as I have discussed, the writer of the Wafer-Thin Document almost always fails to explain the control scheme of Super Mario 64 or Quake in any detail, let alone the scheme to be used by the game in question.

Often these documents spend a lot of time, maybe half their pages, talking about back-story. Usually this back-story is very weak and poorly developed and is only tangentially related to the game being developed. The Wafer-Thin Document also spends a lot of time talking about how the menus will work. Not the in-game menus, but the system menus where users select what type of game they want to play, set their options, and so forth. Many mock-ups are made and options are carefully listed. What exactly the options will affect in the game is seldom described in any detail, since the game itself is barely defined. Figuring out the menu system is something best pursued once the game is working, when the designer knows what sort of options might be important and what different gameplay choices players will have; it is certainly far from the most difficult part of game design, nor the most important system to nail down first.

Wafer-Thin Documents are often constructed by managers who like to think they are game designers. The reason these can also be called Ellipsis Special Documents is that they are often littered with ellipses. For example, the worlds players will encounter in the game will be described in the following manner: “Jungle World is a very hot and sticky place where the Garguflax Monkeys swing around and torment the player...” And that will be all the document provides in way of description for the world, ending at an ellipsis, as if to say “insert game design here.” It is unclear whether the writers of these documents plan to come back and fill in at the ellipsis later or that perhaps they do not deem it worthy of their valuable time to actually explain how their game works. They just assume someone somewhere will fill it in and make them look good.

Another example of the content found in Ellipsis Special Documents might be: “Players will be given an option of many cool weapons. For example, the Gargantuan Kaboom does twice the damage of the players’ other weapons and has a special effect. The Barboon Harpoon will allow users to kill enemies at a distance with a nice camera effect. Other weapons will be just as fun and coo l...” Here the writer of the Ellipsis Special fails to describe the weapons the game will have to any useful level of detail, and then, having listed two weapons, decides to leave the rest up to the imagination of the reader. Of course, readers are very usefully told that the other weapons will be “fun and cool.” The writers of the Ellipsis Special mistakenly think that is all the description necessary to develop a game.

The only upside to the Wafer-Thin or Ellipsis Special Document is that it allows whoever gets to implement the design to pretty much take over the project and turn it into her own. I say this is an advantage, since usually the ideas the manager included in the Wafer-Thin Document are beyond ridiculous and do not make for viable gameplay. But one must be wary. Problems arise when the manager shows up six months later and complains: “But that’s not what I wrote!”

The Back-Story Tome

Unlike writers of Ellipsis Special Documents, the designer who writes the Back-Story Tome spends a lot of time working on her document. These books (it is hard to call them merely documents) usually stretch into the hundreds of pages — 300-, 400-, even 500-page documents are not out of the question. There’s a lot of information in there.

The first mistake these documents make is usually a poor table of contents and the lack of an index. In a design document, well-ordered information and a good table of contents can replace an index, but the absence of both is a huge error. The problems are compounded when the document is as long as War and Peace. The primary reason for the existence of game design documents is to allow team members to quickly look up information about a section of the game they are working on. If a programmer wants to know how the AI for a particular enemy is going to work, she needs to find that information quickly and easily. If she cannot find it, she may just make something up. Similarly, when an artist wants an idea of the textures that will be needed for a given area in the game, she wants to be able to find where that area is described as quickly as possible. Design documents are not read like novels. No one starts at the beginning and comes out at the end. Primarily, design documents are reference materials, and if team members cannot easily retrieve the data they are seeking, they are liable to give up.

However, once one starts hunting through one of these Back-Story Tomes, one is startled to find that, indeed, there is no information about the gameplay in there. It is all back-story. And at 500 pages, it is far more back-story than most computer games will ever use. The history of all the characters in the game, the friends of those characters, and all the relevant parents and siblings are all described in minute detail. It may be very interesting stuff (though usually it is a disorganized mess), but in the end the reader is left with very little idea of how the game is supposed to function. These documents are often the sign of the frustrated novelist or a writer from a non-interactive medium who does not truly understand game development. A lot of games make storytelling one of their central concerns, and a story bible can be quite useful to game creation. In such a case, it makes sense to discuss the game’s story in the design document to some extent. But first and foremost, a design document is supposed to contain the game’s design, which is very different from a game’s story. Remember, your most important consideration when writing a design document must be, “what can the player do?” Though these tomes are very significant in terms of weight and will probably impress the venture capitalists, the programmer who has to work with such a document as her only guidance is going to end up designing the game herself.

The Overkill Document

Some designers think they can describe every last aspect of a game in the design document. It is certainly true that many design documents lack the necessary detail to be useful, as we found in the Ellipsis Special Document discussed above, but at the same time, going to an excessive level of detail can be a waste of the designer’s time as well as that of the person who has to sift through all of that excess information. Furthermore, excessive documentation can lead to the illusion that the designer has created a complete, thorough document, when in fact she has gone into far too much detail about certain subjects while skipping other areas that need to be addressed.

For example, suppose that the game being documented has a number of characters that perform certain actions in the game-world. Say the game has townspeople, and they need to walk around, sit down and stand up, talk to each other, and sleep. The document should describe these behaviors in the AI section. A truly thorough document might break this down into separate animations: stand from sitting, sit from standing, idle sitting, idle standing, walk, converse with hand gestures, and so on. Probably this is not necessary, since good animators and artists will be able to break this down better than a designer can. But some designers may go overboard and actually sketch or list the individual animation frames. This is absurd. There is no way to know in the design document stage how many animation frames will be required for a given animation. This sort of decision can only be made and adjusted during the game’s production. Not to mention that listing animation frames is insulting to the animator who will only feel demoralized by this degree of micro-management. Furthermore, the design document should stick to gameplay design, and not veer into the territory of the art bible or other art documentation.

Another example might be what I call “balancing data.” These are the actual statistics for the weapons, items, and characters found in the game. The design document should probably list what different attributes weapons and characters will have. For instance, a weapon might have a range, accuracy, number of shots, and rate of fire. Furthermore, the design document might want to describe the qualities of a given weapon: “The Double Barreled Shotgun has a short range and a low accuracy, but does a large amount of damage in a large area.” However, actually listing the values for a weapon’s attributes is not very useful in the design document. Saying “Shotgun Accuracy: 2” does not really serve any purpose since the number “2” does not have any context and therefore no meaning. These values are best determined when the game is actually functioning, when a designer can balance the weapons as they will be used by the players and thus the designer can experiment with different settings to achieve the desired effects. Creating large tables full of data before this information is actually testable is by and large a waste of time. Filling in a chart quickly may be a way to convey some raw ideas that were hard to describe through words alone, but at best such a table is a first pass that will no doubt change many times before the game ships.

As with animation minutia and precise balancing data, source code also does not belong in the document. Designers who start writing out algorithms in their design documents are going too far. It does not matter if the designer is also a programmer. There should be no code, not even pseudocode, in the design document. Including code will only serve to bloat the document and distract from omitted information that needs to be covered. Some simple if-then-else type logical explanations may be useful and are completely appropriate. Such examples may help communicate all the contingencies to the person actually writing the code, and if nothing else force the designer writing the document to consider all the possible cases and outcomes that the game will need to support. But by the time the examples start looking like compilable C++ code, you know your document is overdoing it.

If there is any useful information in the Overkill Document, it is so hidden in the river of useless data that team members will be too intimidated to look for it. The author thinks that she can preplan everything, and that she is far more talented than any member of her team. While such excessive attention to detail can be impressive to those who do not really know what they are doing, a design document that goes too far will only infuriate the team that has to work with it.


The Pie-in-the-Sky Document

These design documents often have noble intentions with grand ideas for truly magnificent gameplay. Sadly, the writers of them typically lack any technical grasp of what the computer is capable of or what a team of twenty people is likely to accomplish in a year and a half. As a result, these overly ambitious documents put forth fancy ideas with no basis in reality or feasibility and end up frustrating and infuriating the teams assigned to “make them happen.”

Pie-in-the-Sky Documents include ideas such as “a fully modeled replica of Manhattan will be the players’ primary game-world, complete with AI agents representing all of the city’s seven million inhabitants in real-time.” The authors of Pie-in-the-Sky Documents do not want to be bothered with messy details such as the reality that no existing computer system can simulate seven million humans in any sort of reasonable time frame (let alone real-time). Another feature suggested might be “a natural language parser will be included that allows users to type in full, complex English sentences, which the characters will respond to with their own dynamically generated dialog.” The guilty designer does not want to hear that research institutions have been working for decades on natural language processors that still have trouble with short, simple sentences. When confronted with a Pie-in-the-Sky Document that you must work with, the first thing to do is call a reality check meeting involving key programmers and artists as well as the management who want this document implemented. With them all in the same room, some simple and quick calculations on a piece of paper or white board will often reveal how fundamentally impractical the game proposed is, and if the management still refuses to accept the reality of the situation, it might be time to start looking for a new job. Pie-in-the-Sky Documents are often combined with Ellipsis Specials to create truly wretched design documents, where the guilty designer outlines a completely impractical project without bothering to go into much detail about it.

The Fossilized Document

Any of the above flawed design documents can also be a Fossilized Document. Indeed, a design document that does not necessarily suffer from any of the above problems and was once a fine reference tool will become a Fossilized Document over the course of a project if the designer is not diligent in her efforts to keep the document up to date. I know of no original game project whose design has not changed significantly during the course of its development, and when the design changes but the design document does not, that document starts to become fossilized.

Suppose a programmer on the development team looks something up in the Fossilized Document and the information she finds is out of date. She may start implementing the old, long-since-modified functionality. At some point, a designer or producer who is aware of the changes that have taken place in the design will notice that the programmer is creating a system that is no longer appropriate, and will chastise the programmer for doing so. This creates frustration for both parties, not to mention wasting the programmer’s time. Furthermore, whenever the programmer needs to know something about the design in the future, she will not trust the design document, and instead will go hunt down a designer or producer to find out how a given system is supposed to function. Of course, this defeats the purpose of the document, as the designer must stop whatever she is working on to explain the system to the programmer. This new system may be described correctly in the document, but the programmer is not going to get burned again by using the Fossilized Document. When the designer fails to update the document when design changes occur, the entire document becomes useless. No one can trust it, and as a result no one will bother to read it.

Wiki systems can be great for more easily keeping a document or collection of documents up to date. With Wiki, any member of the team can update a section of the document through their web browser, and full version control and history is supported to prevent the accidental loss of data. So, for example, the programmer who is implementing a particular feature can slightly modify the text of the design document to match how the feature actually ended up working, to add more information, or to link to the newly created technical design document for that particular feature. On a large enough project, keeping the design document completely up to date can be a full-time job.

A Matter of Weight

It is often joked that design documents are not read, they are weighed. This is not surprising given the heft of many design documents and the lack of desire among team members to read them. Shockingly, this statement is often true. I once heard an ex-producer from a major gaming publisher talk about her experience with design documents and the project approval process. She said that the “decision-­makers” would bring a scale to their “green-light” meetings. When it came down to two similar projects that were both relatively worthy of funding, they would take the design document for each project and place it on the scale. Whichever one weighed more would get accepted, the other rejected. Much as it pains me to tell you, if you are in the commercial gaming business and groveling for dollars at publishers, you need to make your document hefty. You need it to be impressive to pick up and flip through. Many will never read it at all. Others will read only the Overview and Table of Contents at the beginning. But everyone will pick it up and remark on its weight.

Of course, many of these super-thick documents contain a lot of information of negligible value toward the actual development of the project. They may be stellar examples of one of the failed types of documents I discussed earlier, such as a Back-Story Tome or an Overkill Document. It is your challenge as the game designer to make the document as practical as possible by providing only useful information in the document, while making it hefty enough to impress the suits. One might want to include a large number of flowcharts or concept sketches or choose to use a bigger font, all while not being too obvious. Indeed, a great game (though a simplistic one) can have a perfect design document only ten pages long. One wonders how many great, simple games have been cast aside by publishers who were unimpressed with the mass of their design documents.

Thankfully, over the last few years many publishers and developers seem to be wising up to the unwieldiness of massive design documents. Design consultant Mark Cerny has been preaching the concept of starting development with only a simple “macro” design document of perhaps ten pages in length that can be expanded on as needed over the course of development. As I have discussed, others are starting to use Wiki as a means of organizing and interlinking a lot of design information contained in many smaller documents. And fewer and fewer publishers are funding development based on a phone book-like design document alone, with prototypes and high-level, graphical pitch documents becoming increasingly important. The days of padding out the design document just for the sake of it seem to be thankfully drawing to a close.

Getting It Read

Once your design document is written, one of your biggest challenges may be getting anyone on the development team to read it. Often, many programmers, artists, or even other designers will not want to put the time into a careful reading of your document. Others may have been burned by bad design documents in the past and will jump to the conclusion that yours is of similarly poor quality. Keeping your document up to date, including only useful information, providing a detailed table of contents, and limiting yourself to practical, accomplishable gameplay elements will help. Including numerous short, high-level summaries before each section of the document can also help team members get high-level information for aspects of the game they don’t need to know so much about. At the same time, such summaries can give readers a big-picture vision before they dive into the gritty details of the document. If your team members sample your document and find it to be of superior quality, they are more likely to return to it for reference when they are actually implementing a given system or working on a particular piece of art. As with any written document, you need to earn the trust of your readers if you hope to keep them reading.

Another key method of getting your design document read is to make it easily available to anyone who wants to read it. Keep it in the same source-control system that your team uses for asset management. You want your team members to be able to get the latest version of the design document as easily as they get the latest build of the game. Since you will be constantly revising and updating your document to keep it up to date with the project (and to prevent it from becoming a Fossilized Document), source control will be a valuable tool for keeping track of the previous revisions. Not to beat a dead horse, but a Wiki system run over a company intranet can also be great for distributing the document to the team, with developers at any time being able to easily read the very latest version of the document through their web browsers.

When you check in the latest version of the document, send your team an e-mail telling them that it is available and explaining what has changed. That way, people can easily skim over the changes. If one of the changes is relevant to their work, then they can get the latest version of the document off the network and read over the relevant updates. Updating your document does not do any good if no one knows you have updated it or if people are still reading old revisions. It is probably a good idea to use a version number with your document, such as 1.3 or 2.7. Include this version number, along with the date, in a header on every page. Often people will print out a design document and not realize how old or fossilized it is. If they can quickly compare a date and a version number, they will know which version of the document they have and whether they need to get a new one.

Documentation Is Only the Beginning

Some designers or aspiring designers seem to think that a thorough design document is, by itself, enough to build a game. Indeed, some companies have had designers write design documents, only to then have those designers move on to write other design documents while a separate team actually executes their design. At its best, a design document is a rough outline, more the suggestion of a game than anything else, and without being involved in a game’s creation until it goes gold master, one cannot truly be considered to have designed the game. A designer who takes any pride in her work will want to be there throughout the project, ready to change the design as necessary to make it the most compelling game possible and updating the document as the design is changed and revised (and rest assured it will be continuously changed and revised). A committed game designer will want to be there to balance the weapons, the AI, the controls, and certainly the levels. She will want to make sure the game follows the focus through and that the initial vision is realized.

If a designer writes a design document and then passes it on to others to actually build, the people who do the actual creation will change the design to match their own interests and artistic drives. The design document will be a springboard for their own acts of creation, not the original designer’s. The design document is an integral part of the game’s creation, perhaps, but a design document is not all that is required. To claim any sort of meaningful authorship on the project, a designer needs to be involved for the duration. In a way, writing the design document is the easy part of computer game design. Actually taking the document and creating a compelling gaming experience is much, much harder.


This article is excerpted from Game Design: Theory & Practice Second Edition (ISBN # 1-55622-912-7). For more information about the book, please visit http://www.paranoidproductions.com/gamedesign.


Read more about:

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

You May Also Like