The "who" of communication cannot be effectively disentangled from the "what."

I will talk to programmers in a very different way than artists about some things, such as algorithm design. I will use the exact same words and assisting devices for other things (like animation or shaders). And the best kind of communication is the kind you don't have to do: I won't generally have a reason to talk to either about audio production.

So there are three things you want to identify here:

• Who are you talking to?
• What are you telling them?
• What do you not have to tell them?

This will usually form a shape that answers the real question, "what do you need to say?" Fill in that shape in the most contextually appropriate manner you can. You will be learning tools and tricks for this for the rest of your career (if you do it right).

Building a good project document is an exercise in applied minimalism: you record the things you need to record, and no more. Expect this document to be "living" - you never just write it and then give it to the team to go implement. These are closely related points, because the more communication you do in your design doc, the more you will have to rewrite every three days when it constantly changes out from under you.


Also keep in mind that GDDs are really kind of a failed methodology. It's far more effective to build tools that let you ask questions about the game as it currently exists than to try and specify every detail and force reality to conform to your documentation. Don't fall into the temptation to write pages describing The Great Orc Warchief and his 15,037 HP and four spells. Build that stuff as content for your game, and add tools (like document generators) that can turn the game data into character spec sheets.

This saves you a ton of time updating your always-invalid GDD, and still gives you tools for things like QA passes (here, make sure this dude dies after 15,037 damage, based on his spec sheet that I just generated from the actual game data).

It's not about design documents, but Chris DeLeon's "Communication is a Game Development Skill" may be of interest to you. His site "HobbyGameDev" is also well worth a visit for the wealth of other material there.

I personally prefer Daniel Cook's idea of design logs to the traditional design document -- a document that evolves during the project and can help to keep the team focussed without having to try to document the entire project up front. For an alternative more traditional view on design documents Ernest Adams wrote about "why design documents matter".

All that aside, you seem to be asking what sort of content can be used to effectively communicate to a team within a document, is that correct? Anything that works! I'd (almost always) avoid code samples, but everything else you've mentioned is excellent.

Diagrams and storyboards, pictures, flow-charts, write-ups describing potential play-through experiences, and dot point (or numbered if order is important) lists all have their place -- use whatever is the most clear for what you're trying to communicate. There are a number of design documents available online -- as you seem to have already noticed, but you can find Tom Sloper's recommended outline (along with links to some examples) HERE -- so you can get ideas from the different approaches those take.

Two important principles:

1. Answer the questions immediately, or don't raise the questions in the first place.
2. Provide the information in need-to-know order.

Read what you wrote and imagine that you don't already know what's in the document. If something you write raises a question in the reader’s mind, you have 2 options:
- Answer the question immediately, or
- Rewrite so that the question is not raised in the first place
Never confuse your reader.
Present the information in whatever order aids the reader in understanding your concept