Design Document Question

When making up a game design document, do you usually document every piece of code that goes into it, or do you just document info about the various libraries, art assets, items, characters, etc?

 

I haven't got into the habit of making them yet - I know, bad Philip! *smack* - but I certainly wouldn't go to that level of detail. I'd be more inclined to make it a high-level specification, and have separate documents for more specific things like the characters, the setting, etc.

 

A game design document shouldn't reference any pieces of code, let alone all of them. Its purpose is to define the look & behavior of the game as seen from the outside. What screens you need, how the pieces can move, what the bonuses are, etc.

The more detail you have your design worked out in the beginning, the faster and smoother the implementation will go. On the other hand, it's rare to find a designer who can work all that out well ahead of time; often more iterative prototyping is required in order to find and polish the fun.

I'm working with one of the exceptional designers now on a game that will be going to Steam Greenlight very soon. It's amazing — he had a clear idea of exactly what he wanted, beautiful art & sound assets to back it all up, a clear description of the rules, etc. We had only a couple of "oops, I should have mentioned" moments in the whole project.

(But then again, this was his second attempt to have it implemented; the first one got bogged down, but probably got far enough to hammer out all the design kinks.)

 

Ideally a design doc reads almost like a story that not only tells you the feel, style, and look of a game and its setting, but also describes the underlying mechanics in a clear and detailed way.

Then you simply take all these mechanics and feel and transport them into a Technical Design Doc, which will go over all the code ideas/reliances/technical hurdles to implement (but not actual code, that isn't needed) and an Art Design Doc (which as many names) that goes over the styles, references, etc. In a larger studio you'll end up with 1 person in charge of each doc and responsible for their design with another person, usually the producer or lead designer, acting as quarterback and ensuring everyone is communicating clearly and efficiently and the documents all stay on target (as changing one item in one doc may radically affect another).

 

GDD should generally be code and engine agnostic. Its a guide for what you are going to make, and why. Not how.

 

I agree. But you do talk about methods such as: Control scheme, AI behavior, and other Gameplay methods. If you start with the design document you'll understand WHAT you have to code much better. It wouldn't hurt to have a folder of scripts to reference even if it's not in the GDD.

 

In my design document I have a general list of the assets required under their section. So a list of sound effects, how they sound and when they are activated under the audio tab for example. I do have some flow charts for menu structures in my GDD, but I am no programmer so I give him/her the freedom to do what they think is right, and I trust in their expertise.

You could go deeper into the coding of the game by making a technical design document in coöperation with the programmer.

 

In my opinion, and I know this will get a lot of disagreement, this is the best thing to do. Unless you work for a big game company and need to document it, it serves the purpose of procrastination for many who cant code and dont want to go through learning.
'Well, I better get to making my game now..Oh wait how convenient I cant make my game I still have a big document to write I guess I'll have to do that later'

 

A design document is not something to use to procrastinate. Blame that on the developer, not the document. We have a design doc and it was the first thing I did. It helps us to stay on course and I can send it to my programmers with notes and it helps them to know what we need for the game. We are able to stay more organized.

Procrastination does not need a design doc....plenty of ways to do that. Playing Witcher 3 for three months, watching TV shows, and videos...visiting the forums. Those all work equally well and a true procrastinator is probably going to procrastinate on the design doc as well.

 

There is that one segment of the community that think a design document is simply a 200 page list of MMO character classes and cool abilities.

 

Like the "perfect MMORPG" guy?

True, having a spec is useful. I think what @ostrich160 was getting at is that getting too detailed when making it is just as bad as not bothering.

 

As a beginner with simple games I use it like a map, to clarify the boundaries of the game (here be dragons is replaced with here be scope creep), highlight key landmarks (mechanics, decision points, effects etc), & the look/feel/sound. Lower level documents then fill in the gaps within those boundaries

 

Thats pretty much the kind of dev Im on about.

 

An interesting subject. Would anybody here be willing to post their design docs? Maybe not for a current project, but maybe for an idea that sounded good at first but was later discarded / set aside?

 

Unfortunately I don't as I may go back to them (I'm to noobish to waste anything at this stage) but I found this which might be useful.

http://www.gamasutra.com/view/feature/130127/design_document_play_with_fire.php

 

Thought I'd add this as well as it might shed some light on our process: http://ironbellystudios.com/gdd-template/

 

I'm pretty sure every developer who is serious about his project will make at least basic documentation describing how the game is going to work before they start working on it.
This wouldn't, as you apparently think, include code or what characters you use, instead it would rather include descriptions of game mechanics and aesthetics of the game that you intend to have.

As for making a scripting reference of your code, it depends. If you have multiple people working on it, or if you might replace your programmer or if you just intend to use some of the code in another similar project then you should definitely document it.

 

Always document your code, preferably before you actually write the code, even if you're the only programmer and it's a one-off script. This clarifies the preconditions and postconditions that your methods and classes must meet. Unless you're writing a flappy bird game in 24 hours, you're going to end up going back to code that you wrote months ago. Documentation will help you get back into the code faster.

 

Kinda late to the party, but check out gamasutra.
They have some awesome articles on design documents, tech docs, and other helpful pre-production documentation writings.

 

Depends. I always prefer self documenting code. Something like this

Code (CSharp):

1. public class ProjectileShooter {
2.     public GameObject projectileToFire;
3.     public void Shoot (Vector3 directionToFireIn){}
4. }

Beats this

Code (CSharp):

1. // This class is used to fire projectiles
2. public class Projectile {
3.     // The projectile to fire
4.     public GameObject thing;
5.     // Use this method to shoot
6.     public void Activate (Vector3 direction){}
7. }

Admittedly my projects are on the small side. But using the self documenting approach I've seldom had trouble reading my own code from months to years ago.

Occasionally I'll throw in a couple of lines of comments. But its mostly to document what I was thinking, rather then to document what the code does. Lines like

Code (CSharp):

1. // This is a mess, fix it
2. // This class is meant to be used by SomeOtherClass
3. // A* algorithm to do pathfinding

 

Good question to ask and to be frank (hey frank) there is no correct answer. When working on my own projects I like to work out what code I will need to do what in my documenting stage. This helps me quickly assess the scope of the project. Not being the greatest coder in the world, it also quickly allows me to see if im going to struggle.

But in the past when I have worked with a team, my friend who is a coder didn't like how this was structure. He prefer the ability to "think for himself", if that makes sentence.

So sorry to give a open answer to your question. When it comes to GDD's, treat them like the pirate code, nothing is set in stone and its more of a guideline than rules that you have to follow.

 

I completely agree with you about that example. Those would be pointless comments, since they just duplicate what's already self-documented in the code. I usually only add comment blocks in two places:

1. At the top of a class to briefly introduce the class's purpose, and
2. At the top of every public method to define the inputs and outputs. This serves as a contract that the code must adhere to, and a guarantee to the caller that specific inputs will provide specific outputs. Contracts make code more reliable, especially when you're working with multiple programmers.

Trying to bend this thread back around to the original topic, contracts are important for design documents, too. Rather than being restrictive, they can be very liberating for artists. For example, if the design document says that a character must be in a specific state by a specific level, this frees the writers to be as creative as they want, as long as they meet that requirement. They're free from the nagging worry that their creative choices might cause problems down the road. And the programmers and level designers can work with confidence knowing that the writers won't totally change things and negate all their hard work.