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. TheWafer-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 cool . . . 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.