How long should a design document be?

There really is no set limit for the length of a design or tech document. They should be long enough to detail out everything that is going to go into the game without added fluff. Design documents might have "fluff" with all of the stories that need to be written, and this is especially true with an RPG.

The Design Document for Forgotten City is around 100 pages. It's a hack-slash game, and the doc would have been longer if we had more time to work on it. Our Technical Document on the other hand is 263 pages right now and growing. Basically you have to ask yourself if you have enough information in the document. If so, then read through the document and make sure that you don't have any unnecessary information. If you do, do what you can to remove it without disrupting the flow of the document.

Don't start coding until the document is done! We started a long time before the document, and got lucky, but that's not always the case. In the future we will definitely be completely documenting our design and architecture before we begin coding. I'm sorry this didn't answer your question completely, but I hope that it helped.

Quote:

Original post by Hrethric I'm sorry this didn't answer your question completely, but I hope that it helped.

No, it did. Thanks, I'd better get back to work.

Depending on the scale of the game, I'd say that 40-100 pages is usually sufficient for a game design document. There are some games that will require signifigantly more or less, say pong and Final Fantasy 10, but for most moderately sized games I'd say that 40-100 pages is a resonable amount.


If I may be so bold as to offer some organizational tips:

Try to keep data listings longer than a page or so out of the body of the document. Appendices are your friend! If you have a listing of, say enemy statistics, make it an appendix. This will keep the body of the document concise and more flowing as well as make it possible to revise the listing later without diging through the entire document. It will also make updating any hard copies you may produce less frequent and easier. If there's a LOT of data, you may even consider making this a seperate document. Dialogue is also a good candidate for an appendix. In general, if you find yourself writing a list that spans more than a page, make it an appendix. If its logically referenced at more than one place in the GDD, thats also a good indicator that its a candidate for being an appendix.

Somewhere in the document, keep a listing of any technical requirements you will need to accomplish the gameplay you are laying out. Do not be too specific or technical, that is what the TDD is for, a technical requirement is not a technical specification. A good example if your game requires scripting would be: "Impliment a scripting solution responsible for functions X, Y and Z; to accomplish this, the scripting solution must support tight integration with the game engine and its data structures." This gives just enough info to aid the technical people in selecting an appropriate scripting solution based on what the gameplay calls for. The quotation above would, for example, suggest that a language like Lua or Python might be good solutions, but that a "command langauge" such as TCL may not be ideal.

If you can, prototype your gameplay. Make a board or card game to simulate gameplay rules. Battle systems are actually pretty good candidates. This isn't so much about the GDD, but it is a game design issue. The earlier you can demonstrate your play mechanics, the sooner you can find out what works and what doesn't and the sooner you can tweak the gameplay accordingly.

Required reading: Joel on Software article about what to have (and omit) in design documents

We design parts. Each part describes what functionality is required, but not how to do it. The size is 'until done'.

Some pieces are roughly designed and sketched out in advanced then filled in as new decisions are made. Others have extensive functionality detail and complete flowcharts and state diagrams for every possible situtation, with the functionality documented and complete before a line of code is written.

For networking protocol, we have 83 pages. It covers everything that can go across the wires, every response, and what is expected for error conditions. There was a lot of up-front work, but it also took months of modifications before the document became stable.

For our compressed resource files, we have a 17 page document. Mostly it covers the languge used to compile and generate the files. It was more of an after-the-fact documentation of how to use the files already in place, but it covers all of the cases we have found with the system so far.

frob.

If you're going to make a technical document, then may I suggest this article?

Quote:

Original post by silverphyre673 If you're going to make a technical document, then may I suggest this article?

I personally dislike this kind of document. We had a few people try to write them, but we gave up.

The problem is that they assume you know exactly how all the modules interact up front. It assumes you understand the system completely before it is written.

That is unrealistic in development.

The odd part is that I've heard people say it is a good practice. Over the past two decades (Eeek!) I have worked with developers at the IRS doing mainframe development, developers doing IBM supercompuer development, developers on old systems that the youth of today have never heard of (like WICAT minicomputers), and several games on various platforms. Although people spout that it is a good practice to define every method of every function in advance, I have never seen or heard of anybody doing it for the long run.

In practice, the interfaces are going to change constantly. You run across the YAGNI principle (you aren't going to need it). Modern design methods have recognised this, and Agile/XP/TDD all tell you not to implement until you actually need it.

With over-engineered solutions, you end up developing something you really don't need, then modify it a dozon times to fit the ever-changing implementation. Then you suddenly realise it was never called and you've been supporting code that the compiler was discarding as dead code. Then you wonder how many hours you've spent reworking code that nobody has ever used anyway.

It doesn't take long before developers stop over-engineering their designs, and begin under-engineering them.

First, design expected user experiences in detail. Make design decisions about how things are to work. Don't describe the implementation. Each user experience should be ranked in terms of importance. It is vitally important that users are able to navigate the menu system and control the character. It is somewhat important that the avitar skid to a stop after running, rather than come to a dead stop. It is minimally important that the character say idle banter messages when you leave the controls alone for two minutes. That way you know where to focus your energy, and what you can safely abandon when schedules get tight. Note that this document should be basically complete before implementation begins. This is the final game. It should look fun on paper. Well, fun if you are a very detail-oriented gamer. [wink]

Incidently, this is also a document you share with your publisher as part of your contract, assuming you do that sort of thing.

Examples:

For your AI, describe what you expect from each part. Under this situation, run away. Under another situation, go in with guns blazing. Under some other situation, shoot at Slippy Toad. The design shouldn't care if you are using a bunch of nested ifs, a state machine, Parzen windows with memorized reactions, or a hopfield network.

For player control, explain that x is shoot (or select on menus), o is brakes (or cancel on menus), square says nasty things, R1 and L1 cycle through weapons, and triangle is self destruct. Don't bother explaining how they are implemented and what messages are passed through each subsystem.

Next, design how parts communicate. Some pieces will require a great deal of design, others require very little. This is going to change frequently over the course of development.

A network protocol needs to be functional before you can start implementing it. It will also evolve over time. Less detailed commands may say to pass a scene graph object, or a player action object. You describe basic underlying infrastructure such as having a message event bus, and some of the commands you will use, but don't bother too much with the implementation details up front. Integrate your parts early so you can begin refining the implementation to meet the actual needs.

Finally, Implement to meet the designs in any way the developers see fit. You know your AI is good enough when it runs away, attacks, or shoots Slippy at appropriate times. You know your UI is good enough when the testers have pushed all the buttons on every screen, and they act the way they are supposed to.

As always, your results may vary, void where prohibited, and some exclusions apply.

frob.

Here is a simple design spec. It's about three pages, four if you include some prototype artwork.

The main point is it nails down all design decisions.

This a basically complete spec. It is something that I could give to any contractor or programmer, along with some prototype artwork, and they shouldn't have any problems with it. Unless I missed something, but hopefully it would be caught early.

The document does not say how things are to be implemented. It gives them enough latitude to be creative with additional details.


Design spec for unnamed game, clone of common game.


Maintenance
This document is maintained by frob.
Please report any flaws in the design.

Proposed game title: L33t b0m Hun7er

Overview
This is a casual game, with an expected playing time of between 7 seconds and five minutes.

This is a prototype display:
<<>>

A window is displayed on the screen, with a normal OS-drawn menu.

Player is presented with a grid of buttons. Some of the buttons are secretly marked as "Bad" buttons. Player pushes buttons. If the player pushes a "Bad" button, they lose and all "Bad" buttons are shown. Player wins when only "Bad" buttons remain unpressed.

The time from the first button push to the end of game is recorded. If a player wins the game, their can enter their name on the "Fastest Times" list where their name and count of seconds are stored.

Prototypical Player
Bob, who is attempting to put off all work until 5:01 PM, plays the game continuously, in an attempt to have the "accomplishment" of setting a new high score.

Amy, who doesn't have an Internet connection but somehow managed to get a copy of the game, is trying to prevent her mind from doing less important things, like thinking. Instead, she plays the game to maintain a pleasant state of numbness.

Startup
The configuration data is verified for integrity. An MD5 hash of the configuration will be preserved. If the configuration data is not present or does not hash to the recorded MD5 value, the configuration is reset.

The game immediately passes through to gameplay once the UI is presented.

Configuration
The configuration data contains statistics for fastest time and the dimensions of the game board. An MD5 hash is also maintained.

The default configuration is a 10x10 grid and 10 "Bad" buttons. This configuration is called "Easy". Other preset configurations are "Medium" at 15 tall x 20 wide and 20 Bad, and "Hard" with 20 tall x 28 wide and 50 bad.

The fastest time for each game difficulty is a name of up to 100 characters and their count of seconds.

The default fastest time for each difficulty is "l33t haxx0r" with 999 seconds.

Each modification of the configuration data results in a recalculation of the MD5 hash. Modifications are immediately saved in persistent storage.

Menus
"Game" menu, containing items "New" and "Quit"
"Difficulty" menu, containing options "Easy", "Medium", "Hard", and "Custom".
"Help" item.

"New" restarts game play.
"Quit" terminates the game immediately.
"Easy", "Medium", and "Hard" modify the configuration data to use the corresponding configuration described above.
"Custom" displays a dialog box where the user can enter the size of the button grid and count of "Bad" buttons. The minimum values are 10 high, 10h, and 1 bad . The maximum values are 30 tall, 50 wide, and 99 bad.
"Help" displays the help file.

The menu is available at all times through the OS.

Selecting a menu item pauses the gameplay timer. The game play timer does not resume until the player clicks on another game button.

Gameplay
At the start of gameplay:
The dimensions of buttons are loaded from the configuration.
The count of "Bad" buttons is loaded from the configuration.
All buttons are initialized to an unpressed state.
The gameplay seconds timer is reset.
The game enters the Wait State.

Wait State:
The display is updated and waits for user input.
At least once each second, the display updates the gameplay timer.
If a player selects a point outside the game area, the gameplay timer pauses.
When they select another point inside the game area, the gameplay timer resumes.
When a player selects a gameplay button, logic flows to the next condition.

If this is the first selected button on the game board:
The configured count of "Bad" buttons are randomly selected from the set of all buttons. A button cannot be selected as "Bad" more than once. The button the player pressed cannot be selected as "Bad".
The gameplay seconds timer begins.


When a player selects any button:
If the button selected is a "Bad" button, play immediately jumps to the Loss Condition.
The neighboring buttons are queried for "Bad" buttons, and a count is maintained.
The artwork for the count is drawn over the button. The prototype artwork is a blank image for zero, and colored numbers for 1-8.
If the count is zero, the system automatically selects every neighboring unpressed button since there none of them are "Bad".
The Victory Condition is checked.
Flow continues to the Wait State

Loss Condition:
All "Bad" buttons are displayed with the embedded artwork.
The gameplay seconds timer is stopped.
No further button presses are accepted.
The text "lol j00 r teh suxx0rs!!!11!" is displayed.
Gameplay ends.

Victory Condition:
When the count of remaining buttons matches the number of "Bad" buttons, and no "Bad" buttons have been pressed, the player wins. Otherwise flow resumes to the caller.
The gameplay seconds timer is stopped.
No further button presses are accepted
The text "You are teh Winnar!!1!!" is displayed.
If the gameplay timer is greater than the best time in the configuration data, the additional text is displayed:
"You are also the Suxxors!1!! {NAME} pwned with {TIMER} seconds!" where {NAME} and {TIMER} are the configuration values for the fastest time.
If the gameplay timer is equal to the best time, this additional text is displayed:
"{NAME} pwned with TEH SAME TIME j00 DID!!1!".
If the gameplay timer is less than the best time, this additional text is displayed:
"j00 totally pwned {NAME} who suxxored with {TIMER} scenods!1. Type U R name:" The interface then accepts the players name. The name and time are recorded in the configuration data.
Gameplay ends.

Optional behavior
Ability to place and remove flags on buttons. Flagged buttons cannot be pressed. Users can do this to mark suspected "Bad" buttons.
Sound could be played when buttons are pressed
Button presses could include animation artwork
User-provided artwork or background skins could be used
Background music could be played

If you have some other optional behavior you would like, please notify the document owner.

END

Enjoy.

frob

I suggest one whiteboard, entirely covered with illustrations.

Quote:

Original post by Fingers_ I suggest one whiteboard, entirely covered with illustrations.

So do I.

It's good for figuring out portions of the work and deails of implementation.


But after the idea is worked out, it needs to be put in a document, stuck in a binder, and used as evidence when the project is cancelled used with the publisher to get funding, and give the developers an exact model (rather than sketched idea) of what the game is supposed to do.

frob.

Frob - I like the design. Nice, straight to the point.

Good topic, this was one of the most confusing areas for me. Never knowing how much to put in or ommit. Seems like I always got lost in the design and talked myself out of the project. . .

The answer is simple: Make it as long as it needs to be. No longer, no shorter.

Length is cost, content is value. Only make it longer if you add enough content to justify the additional length. If you can make it shorter without losing any content, don't hesitate :)

Thanks everyone for your awesome input helping a beginner with this. A variety of ideas, definitely from those who have experience with the topic. frob, the example was also extremely helpful.

Mine tend to be between 1 and 10 pages. I am a believe is play testing and expanding, so for me a huge design doc would eat into dev time. However, I am also the only programmer at the studio, so my preferences serve only me, not other programmers.