How long are your design documents?

#21 Kenneth,

If I were in charage of a $25MM project, then I would probably want a QA person in the project from the start to build test plans for modules, data integrity, etc. But, $25MM is bigger than the entire Dynamix budget was for an entire year. Getting your head around our projects was trivial compared to what you are doing.

The biggest budget for one project that I ever worked on was $3.5-5MM. That would barely qualify as a milestone or module for a project as large as yours. But, large budgets and huge development teams is becoming much more common. Some large projects are running into the $12-14MM range, so full on QA people will make sense.

Jeff Tunnell GG

#22 Hehe, remember Shenmue for sega Dreamcast?

$50+ million dollars to develop.

I mean, if everyone who owned a Dreamcast and their dogs could have bought two copies and they'd still be in the hole. How could Sega have let such a financial snafu occur?

#23 Of the 3 commercial projects I've worked on so far the design doc size has varried greatly...one company had a 6 page doc (ugh)....andother had two 300 page docs that covered every little things (insane)!

#24 They Game Design document can be as long as you want.

I like to start by writting a Treatment. It's basically, a short document (NO MORE then 3-5 pages), that doesn't go into detail (don't write like your selling the game). It's purpose is to get the game concept clear in your mind and work out problems with it. Then it to your team, they help you remodel it a little. Then you do a Design Doc, and Designers Notes. The design doc can be as long as it needs to be. Basically, to be less confusing, don't write down why you have chosen to do something, thats what the Designers Notes are for. As you are writing the design doc, you also write the designers notes to corestpond with it.

One thing that I hate are treatments, (or stage 1 docs) that try to sell the game insted of being honest and working out where the holes and bugs are in your thinking.

Skye Gellmann

#25 Very simply put there is a formula for calculating the complexity and risk percentage of a project.

Implementation effort is inversely proportional to the complexity of the request for the work to be done.

In plain english the shorter the request the more effort it will be to actually get it fullfilled because of all the things that are NOT mentioned in the requirement that you find out along the way.

#26 My design docs tend to be short (3-5 pages at most) but my todo lists get long

#27 Jarrod: That's just plain wrong, and there are enough counter-examples I that I don't think I need to go into it. Basically your formula is longer = better.

Scott McGlasson: Damn, I didn't realize the post wasa year old. Wonder how it turned out.

I was goint to post the link I posted in another thread:

web.archive.org/web/20020607065537/zileas.com/articles/lecture5-new.phtml

Something important is that, in your case, it seems like overkill to come up with a description of item weights.

I would say "your inventory is limited by weight." Then for a given weapon say "bazooka is pretty heavy." That really should be good enough.

Things like "heavy" "light" "fast" and "slow" have meanings. The problem with numbers is that they don't really have a meaning. Is 200 kph fast? Is 10 pounds heavy? Depends on everything else. (If you are a giant robot, 10 pounds is not heavy)

I would assume things like item weights would be configurable easily. Things like that are hard to pin down and there is 99% chance they will require tweaking and testing. So I would say, give them general meaningful english descriptions and save the actual numbers for later.

The example I always use is:

1: "A zergling is fast and small, high attack speed but very low hp"

vs:

2: "Zergling moves at 16 kph, 3 meters long, attacks once per 1.2 seconds and has 200 hp."

The second basically has no meaning on it's own.

#28 Jarrod, are your eyes brown by any chance?

#29 You all miss the point.

When someone asks for something and does not go into enought detail and a developer ACCEPTS the request without doing due dilignence in requesting more information or makes assumptions about the implementation from a partial discription that request is to short.

In your example James you "assume that things like item weights would be configurable easily" well what if someone else "assumed differently" and then found out near the end of development that guess what, the gameplay designers want to start tweaking stuff and it is all hard coded into the engine.

I would then be right that "your inventory is limited by weight" is incomplete and causes more problems than if it was more COMPLETE.

I agree that terms like "heavy" and what not are more useful that trying to spec things out to infinity, but there is an ambiguity in that that bothers me also, there is an ambiguity in that something that is "heavy" needs something concretely defined that is "not heavy" for relevance. For fuzzy requirements like that you need some relative base line context to judge from.

If the true requirements are that "your inventory is limited by weight and that wieight shall be easily configurable by a non-programmer" then that is what it should say. That simple side effect that you "assume" completely changes the landscape of the scope of the implemenation.

Funny thing is how my simple statement got extrapolated to something that it does not say at all. Which proves my point even more.

I never even mentioned numbers and all this other mintuea, you ASSUMED that! Which in an indirect way proves my point. There was not enough of a complete statement to remove all ambiguity.

And that is the crux of that theory, you have to have enough requirements that there is ZERO ambiguity. Anytime I find myself "interperting" some requirement or request, I stop and go back to the source and get clarification.

#30 What is so wrong with asking for clarification? That's a greedy method that ensures you get the exact amount you need. Having too much info is a problem. Covering all the bases is good, but that can quickly turn into covering way too much. Too much is no better than not enough.

Specs are always ambiguous at some level. How detailed the spec is is related to the level of people around you. I wouldn't tell an expert game programmer that item weights should be configurable, any more than I would tell them that quicksort is faster than bubble sort.

This should be enough:

"Items have an easily tweaked weight, and inventory is capped at a max weight value." Any competent programmer can take it from there.

---

What you said is:

"In plain english the shorter the request the more effort it will be to actually get it fullfilled "


AKA, longer is always better. Maybe that isn't what you meant, but that is what you wrote. You also neglect to include the fact that producing requests takes time, and producing overly-detailed requests or requests that later need major revising is a waste of time.

Obivously you want to avoid people having to constantly make guesses about important things or asking tons of questions, but that isn't just a function of length of description. Being concise and knowing how much information is useful and how much is too much is important.

I'd like to see evidence that a splendorific detailed plan produces results. I know plenty of games that turned out well and did not follow your methodology. (For a laugh read the "design doc" for Doom, it is floating around on the web somewhere)

If you want to claim that some design creation methodology works well, where is the evidence? I can think of tons of examples of games that came up with elaborate plans and ended up changing them - that's just a waste of time.

#31 The problem with asking for clarification is that you have to think to do it. Sometimes you can read an ambiguous spec and think 'Yeah, that's obvious' and run off and implement something quite far from the intention behind the requirement.

I worked in consulting for a few years - this happens _all_ the time. After a few projects you figure it out and get the specs clarified up front, but the new guys always seem to make that error.

When you're dealing with an internal designer on site, it's no big deal - they look over your shoulder and catch errors quickly. 'Virtual teams' with scattered members working mostly independently would do well to make their requirements as clear an unambiguous as possible.

Quote:If you want to claim that some design creation methodology works well, where is the evidence?

Contract law sucks. :) I could site a dozen software projects where proper planning headed off a problem and shortened development time. But I'm under NDA as far as internal business practices are concerned, so I can't say anything specific.

I wouldn't call a good design or development plan necessary by any means, but they often save time and help conserve and intelligently allocate resources. They don't make games better - they make games cheaper to produce, though.

#32

Quote:
How long are your design documents?

Not as long as this thread. ;)

#33 Brad.. your just lucky!!
mine is the size of each and every msdn version combined.
+ appendix.

#34 @Badguy:

Don't worry, the thread is quickly catching up to you.

#35 17 pages - 5-10% complete...

#36 My design document for the game I'm just finished up is 0 pages, but the design document for the game I'm just starting is about 5 pages.

I'm going to have to change it over to html though because of that accursed wordpad format...

I was just complaining a bit there. I hate all text formats except .txt and .html, but I was using that design document template that was posted here and didn't bother to change it to html.

#37 Hello,
I am from a different industry professionally, but I have always aspired to make a "Great Game". From what I gather game development is VERY R&D for new concepts and game ideas. Many people seem to have an idea of what will work for gameplay. However, if you assume the idea you have will be fun in a product you may be wrong. Hence, design vs. reality. It may be a "cool" idea having different weights for inventory with a maximum amount of carrying capacity, but it may be cumbersome to the player in a high speed FPS. (Please note that I do not know what kind of game the person who started this thread is writing. This is just an example of what could be overdesigned and just gets thrown out.)

The reason I mention that I am from a different industry is my involvement with an industrial R&D project. In this project I served as an integrator (put stuff together for the controls), programmer (PLC), electrical engineer, and the interface designer (HMI). This project has run into over 6M in cost.
The original design was based on an idea of a PHD (a very good idea). The system was built according to how the concept was "thought" to operate. Flowcharts were made to show how the system would operate. It was my job to translate the flow charts to PLC code. I also helped build the flow charts. I then spent 6 months programming the system to operate this way.
When we finally started testing we found that 95% of the coding effort was useless because the system did not behave as expected. To this date we are using only a small fraction of the original code. Now, after this experience, I am of the opinion that for R&D projects you should apply the "Fail Forward Faster" design approach. Do as much reality testing up front before you spend a LOT of money on a concept. Get an Alpha showing the concept before you go into detail. Apply the "Is it going to work?" test often. For games I would imagine the test would be "Is it fun?".

Since I have no direct experience in game development that is the only information I can provide. I have my own opinions on how it should be done. But, until I have my own experiences under my belt I will have no wisdom to impart on the subject with any authority. So take my example for what is it worth. If there is a "turn key" game concept then maybe huge documents are worth it. However, unless you know "it is fun" then a document describing how to make this "fun" has no meaning.

Thanks,
Frank

#38 Some of my guidelines for writing game designs are as follows (in very poor order) -

1) Keep documents modular. If a gameplay machanic or concept can be used in a different game, put it in a separate file, and link it into current game's document. I like to be able to totally configure a game from buiding block documents. This way you can link in all the possible different design options, and pick which specific ones you want to use when finalizing the design for a specific game.

2) This leads to another principle - be as general as possible. If a detail is unecessary to the principle or idea expressed in the document, leave it out. This is not only to avoid irrelevant details, but also to keep design documents modular and reusable.

3) Don't just design one game at a time. 2 different designs ideas can be excellant, and you may have an initial tendancy to want to put them both in the game you are currently developing, but this is often a really bad idea! Just because you thought of them while designing the game doesn't mean they should be used in the same game! Games must be cohesive and streamlined in order to be a) functional and b) finishable. All of a game's designs must be compatible with one another, or else you'll end up with a broken design. The pieces must all fit together in a synergistic and complementary way, or else the sum will be far less than its possibly very innovative parts. This is another reason to keep your documents modular - to keep your concepts separable for the time you do need to get an idea down, but also keep it out of the current game, and ready for one you may make later.

4) If a game concept might not be perfectly clear - elaborate with pictures and diagrams, but never go off on a design tangent. Express the idea, express it well, and express it in simple, direct, and singular manner. Try to have only one major game mechanic per low-level game document. Later on, when you put them all together in a specific game, you will link them in, and document how they act combinatorally to reach the game's goal.

5) List your game's goal, and create and configure your game's ideas and mechanics to meet them. Your game's goals should be like a company's mission statement - short, HIGHLY general, adaptive, and able to inspire a vision in those who see it without describing concrete details.

6) Consider designs combinatorally and in aggregation in a new, higher level document. If you want to document a synergy or even a problem with the combination of 2 game mechanics, do so in a different document, and link the involved design document into it, then link that into the current game document. Try to keep design ideas separate, modular, and hierarchical.

7) Think of your design as a general, overall goal, and make detailed, implementation-specific decisions outside the main document. Your main document should be your guiding principle, your "constitution" of sorts. It should be something you look to for purpose and direction if you lose design perspective along the way. The concrete documentation and details should come later, and in a separate document. I prefer to leave all details for when I'm actually developing the game. That allows me to be dynamic, adaptive, and iterative. Unless I'm using a concrete example to describe a concept, I try not to write concrete details into a main design document.

8) Be suggestion-oriented. If you do have concrete things to add to you document, always link them from an external file, and always speak of them a "suggestions" rather than anything set in stone. Very little detail should be set in stone in your main design document.

9) Prepare for design failure. You NEVER know when a particular design or concept will fail. There are so many ways in which a design can fail, I won't even enumerate them. This another reason to keep your designs general and modular - you may have to replace entire chunks of your game design later on.

continued...

#39 10) Allow your teammates to have a lot of creative freedom by NOT filling in details for them. Every teammate should be allowed to visualize their own vision for the game within reasonable limits. You should only provide enough detail in your documents to keep everybody on track and on the same page. Your design document is to focus on the GAME DESIGN, not a certain stage's design, or a certain character's design, or anything else that does not directly involve game design mechanics. Noone should put these types of details into the main document, even if everyone agrees on them at the time. These concrete details need to be put in separate, higher level documents.

So, I try to think in terms of modularity and reusability, generality, separability, directness and simplicity, principle, hierarchy, flexibility, and failability.

In not so many words, think like a software engineer! Design your design documents like you would design your software framework interfaces - with as little concrete implementation as absolutely possible, and in small iterative modules refined and fleshed out during development! :)

#40 In my experience, as a rough basis, your final spec doc should:

- be a playbook with every game mechanic, every function, every algorithm and calculation the system needs to accomplish
- be an art guide with at least sketches of concept art for every single item which will be drawn in the game
- be a music guide with descriptions of every single peice of music and sound effect in the game
- be a map book, with detailed maps of every region in the game, showing the location of every object, with correlations to the art guide for every peice of art to be displayed
- be a marketing guide, with rough "selling" points of the game, a "vision writeup" of sorts that describes what's special about the game

I'm talking off the cuff too, so I'm likely forgetting stuff. ;)

The "as long as it needs to be" bit is very accurate. Some games might take as few as 40-50 pages. Others might take over 200...