1. Write with active verbs in the present tense and use consistent perspective viewpoints.
2. Use bullet points. Lots and lots of them. And indented ones. Make the document bulleted as much as possible because bullets force you to think in terms of short sharp points. Always use the same bullet point style.
3. Keep your document map consistent. Actually, step back two from that: Learn how to use MS Word Styles properly, learn what a document map IS and then keep your document map consistent.
4. Use diagrams. Lots of them. Visio-style diagrams are fine. Use the diagrams to lead your points and explain the complicated things as simply as possible, and the bullet points to support them.
5. Edit. No, really: EDIT. I honestly think no doc should be released from design until it has had at least 3 passes from first draft to final version. One for content, one for flow and the last one for mistakes. Have an editing loop whereby the original writer makes all the instructed changes. The editing loop is the single best way to make your writers better at their jobs if only to avoid feeling humiliated.
6. Build the GDD/whatever document from a series of consistently formatted and written spec documents. These can be in wiki or in doc form, whatever suits you better. Writing GDDs from scratch is a pointless waste of time. They should be built alongside prototyping. A spec doc is simple to write and revise in the face of reality. A whole GDD is a nightmare.
7. Somebody needs time in their schedule to maintain and loop old documents so that they do not become irrelevant. Somebody else needs time in their schedule to edit those changes and loop them back to the writer.
8. Design documentation should not be either fiction or technical documentation. The job of design documents is to explain, without recourse to vagueness, pretentiousness, game theory or windiness, what the player can see, do and hear in the game, how those things work from the player's perspective, and the supporting game rules (not technical specs) that are needed to do that.
Everything else is guff.
This makes me think I should start some sort of freelance documentation editing/teaching company for game developers. Documentation is as much a problem as it was 5 years ago, and sorting it out is something I'm really good at. What do you think?
Particleblog's comments have moved to The Play Room.