Design Documentation is a Many Strangled Thing #1

What happened these days?

Woohoo! I wrote the 100th exercise for “Treasure Monkeys” last week! (Party, party, fireworks!)

100th exercise

The 100th exercise!

The vision of the game became crystal clear by now.

I’ve already gathered rough estimations about the cost of production. Now I can collect more informed estimations. Since I already finished the art and sound asset list, there is one type of documentation left: the documentation for the programmer. And after I used several different forms and complexities of doucmentation during my job history, and none of them was optimal, I want to try something new. In want to try something that I call “iterative documentation by requirements”.

Documentation is more than one file

Before I go any deeper into the subject, I want to clarify one thing: Design Documentation is not only one document. “The Design Document” is often named and referred (and means a more or less detailed description of a game), but during the design process more than one documentation form is necessary. They are necessary, because there is no ONE omnipotent document which unites all requirements and properties.

If you look at what a design document has to provide, you will understand.

A document to inform them all

Every department which is working on the game needs different information.

A publisher for example, needs other information than a freelance programmer, an in-house artist needs other information than an external QA service company. Some information intersect, but some are completely irrelevant.

Language matters

The document comes in a language that every participant understands. And the designer has to structure and verbalise all information in an understandable way.

Be precise

The perfect document contains enough information to be understandable, but is short enough to be readable. I’ve seen enough super detailed documents which were never read.


Rage Comic created with

It is hard to add the right amount of information, but there are some hints for making precise and readable documentations:

  • no nested sentences!
  • use tables
  • prefer bullet points over sentences
  • prefer pictures and schemes over words
  • add examples

Always up to date

It is a natural process that the game changes during the development process. The better the preparation, the less changes, but some things just can’t be predicted. Changes, even little ones, will happen and will have to be documented.

The more complex and long your documentation is, the longer you will need to update everything. And you will make mistakes on updating. The longer and more complex the documentation is, the more mistakes will happen.

Let’s say you have a character named “Mr. X” and someone (you, the producer, the publisher…) decides that the character should better be a woman named “Mrs. Riddle”. The name and gender has to be changed at every point in the document. Only one mistake can lead to wrong voice recordings. “But you can search documents!” you may think now. Of course you can. But what if “Mr. X” is referred as “the protagonist’s mysterious uncle”? Also you can not search text in pictures. Oh and even if you make it and change every reference to “Mr. X” into “Mrs. Riddle”, you can bet that someone in the team will continue talking about “Mr. X”.


How bad documented changes in the game can destroy gameplay. Rage Comic created with

Some Words of Wisdom: There is no “jack of all trades” document.

It may be theoretically possible to combine all those requirements in one document, but as far as my experience goes, the amount of work is too high to justify the benefit. Armies of game designers would have to write and maintain the document, to keep it up to date every day.

After encountering too many incomplete and/or outdated design documents, I’ve come to the conclusion that it makes more sense to write down and maintain only the currently needed information.

What this means for “Treasure Monkeys” I will tell you in the next article.



This blog is about learning game design and game development. Please do not steal my pictures or other content. If you want to use something, ask me!

This entry was posted in Developer Diary and tagged , , , , , . Bookmark the permalink.