Writing Design Docs

Brenda Brathwaite recently posted an excellent article on creating a game design doc. Her best advice:

Before you start writing, consider is your audience. Many new designers write documents as if they’re being written for gamers instead of a programmer who’s tired, annoyed and up at 3 a.m. coding your combat system…

So true! Even if you’re just writing implementation notes for yourself, this is an important thing to keep in mind. When there are a lot of complicated rules going on, it’s easy to get bogged down with loose ends when programming the implementation. Unfortunately, this sometimes means important details get overlooked. A careful and detailed list of requirements without a lot of extra hype cluttering it up is invaluable as a checklist when the going gets rough. It will help prevent anything from being missed.

Writing the right amount of detail is a fine art. You need enough detail to make sure everything important is explicitly defined, but not so much that the document becomes so overwhelming that you–or your team–will be tempted to just skim over it when you refer back to it later. Personally, I’m a big fan of writing design docs in html help file format, mainly because most of the editors force you to create drill-down type topics instead of writing the document linearly. Incidentally, many of the editors will also let you save to PDF or other file formats… it’s not the file format that’s important, as much as the concept of writing hierarchically instead of linearly.

Hierarchical format is very helpful when implementing because it allows you to keep track of the big picture with fewer minutiae details in the way while blocking out the architecture, yet you can focus in on the important-yet-tiny things when you implement the specifics. If you have the discipline to do it, keywording individual topics is also immensely valuable as the document grows in size. When programming large systems so many components end up more interrelated than people realize, and good keywords are another tool that help find everything important when you’re coding it up.

Tags: , , , , ,

Comments are closed.