Design documentation

A large part of my job is to write, re-write and give feedback on game design documents. I also give lectures at a private school with game design classes. And there is a bunch of beginner mistakes that I often see from students and design interns.

Creative instead of technical writing

...because it also illustrates typical art drawn by game designers

Great image for Creative Writing

There might well be a place for you to vent all that creative energy. You could take up pottery or painting as a hobby. Just don’t try to build your professional game design career on that one cool D&D campaign you DMed with your friends. Hell, even the game documentation that resembles regular Pen & Paper sourcebooks the closest – World and Style guides – still requires you to be primarily structured, comb out the filler words and get the information across.
This whole posting could be summarized into “It is TECHNICAL writing, stupid!” and some links to freely available, excellent online guides on the topic. Seriously, there are huge differences between a game writer and a designer job. And if the application you replied to clearly states “looking for designers”, then do not try to sell yourself on your awesome creative writing and that fanfic you wrote months ago.

Confusing documentation types

Surprise! There are a lot of different documentation types when designing games. All of them have specific purposes and audiences. A pitching document, for example, is used to sell a project to potential investors. So, yes, you are allowed to use some marketing speech and even drop the occasional “epic” and “awesome”. It should be clear and to the point, and consist not solely of a detailed description of your background story and characters. A “Detailed Design Document” or whatever you call your main rulebook should contain just that: The rules of the game. Ideally in a way that is easily understandable by developers and producers. They care less about the intricate happenings in you game’s universe last centuries.


So, yes, from now on I will allow myself more variation in the blog layout

Can you spot it?

This beginner’s mistake usually comes in two forms: Inconsistency of layout and inconsistency of content. The first one creates a rag-tag look of document pages that forces readers to slowly scan the whole page and figuring out where the bit of information they need is placed this time. This can be avoided by establishing strict templates and formatting rules.
Inconsistency of content usually happens when no design glossary and structure is present. Suddenly, you got five different names for the same object, designers argue about semantics and every time you ask someone “What ‘resources” exactly?” you get a different answer. This is even more pronounced when the documentation is not written in your native language (yes, we are writing documentation in English but talk is still German). Some English terms get rapidly over-used, since the synonyms are not easily available to all readers. A glossary may help, but ultimately you need really good communication between team members or everyone will stay in his own definition spaces.


Do not put your balancing values into the design doc. Ever. It’s alright to give some indicators like “[few] hitpoints or [max] level”. It’s also good to include relations like “this item type is stronger than all the others” but avoid precise numbers. The reason should be obvious: You will never be able to keep your design document up to date.  Just accept it. The moment you start tweaking your game values, you create false information in your documentation. This could be overlooked if not for one caveat: If THAT information is false, what about ALL OTHER information on that page? You just made your audience disbelief your documentation in general. If you are a social person that can be nice, since now every developer will come to you to ask about the “correct” feature status instead of trusting the doc. Unfortunately, answering these questions all day will keep you from doing any other work you had scheduled.
Concerning work: Over-specification creates a lot of text that gets obsolete very fast. When you hit production phase, the priorities shift and features are iterated. And while that won’t be much of a problem for style guides and feature targets (and those shouldn’t change once production has started, right?!), detailed information does not survive when hit by production reality. Your only chance is to create living, flexible documents without week-long feedback and approval cycles. Mindmaps are very useful for this. That way you can keep up with production and iteration speed and give your developers precise and current implementation information.

Trying to solve everything in text

...because I can not understand it even before starting to read

See, already better than having to read all that in running text

It’s the old “show, don’t tell” maxim. Sometimes it is enough to put a nice image in the header area of a page, so readers can more easily identify the topic. Apart from this visual anchor, images can greatly improve the readability of a feature descriptions. Take this example: “…then the player clicks on a button and a popup asks him if he really wants to pick his nose. If he has enough resources left, the ‘yes’ button is available, otherwise it is greyed out. The ‘no’ button is always available and will either close the popup or show a security popup to confirm his choice if his booger level is already at 23%, in which case…”. After how many words did you space out? How many different cases could be coming that modify the previous sentence?

The above information can be easily communicated with a flowchart. And concerning flowcharts, please stick to these basic guidelines:

  • No excessive use of colour and form. If you have to, include a legend and use it consistently.
  • Make straight arrows, nothing diagonal or curved.
  • Put the start of the chain in the top left corner (or wherever your regional reading customs usually start scanning a text).
  • Do not put additional descriptions in the chart. It should be self-explanatory without much reading.
  • Avoid uncontrolled growth. Charts tend to contain a lot of interconnected features. Focus on the one aspect you want to explain instead of putting the whole game into one image.

Well, that should be everything for now. Documentation done right is extremly useful in many ways, and essential if you work with top-down design structures. But please, make it relevant and easily readable. That way, you are helping designers around the world in the constant struggle to get developers to accept documentation.

UFO sightings

The red numbers on the side indicate he dies in three seconds

The old

Usually, I will not comment on the current news cycle, but this is one is too good to pass up: There will be a new UFO game. It will be turn-based. And it will be made by Firaxis (the Civilization guys). So how about that?

First reaction: Great! “Turn-based tactics” is the one genre I love unconditionally. It has something to do with the slow pace and the option to min/max a party of characters. Because what is better than gaining a Level-Up after a hard mission? Gaining six Level-Ups, of course! And UFO – Yes, it’s XCOM in the US. But I’ll stick with the European version thankyouverymuch. It will always be “UFO” to me. Many hours were spent manoeuvring the fleshy, vulnerable humans attached to my alien-killing weapons through dark neighbourhoods and farmland. Or cruise ships. Yes, I completed Terror from the Deep. It felt so difficult that I have the need to mention this achievement over a decade later.

Well, UFO had one of the best meta-games of any entries in that genre. It did not try to cram a story down my throat, but gave me the whole world to play with. And the story wrote itself from my decisions. A Terror Mission in Tokyo? Well, I probably should have patrolled that area more diligently. A large Spaceship is approaching my base, and the soldiers are still out on a mission? Quick, get some rookies and hope they don’t do more damage to the equipment than the intruders. Discover the alien base on Mars? Better have enough units and funding left to actually get there. Ah, it’s all coming back… So, loaded with enough nostalgia to kill an elephant, have a look at the first information from the new one.

You are allowed to streamline… a bit

There are five units in this picture. Can you find all of them?

The new

The screenshots give me Hex grids and blurry terrain textures. I have seen that somewhere else. It looks like the missions are played in the Civilization engine. Thinking about it, there were some mods in Civ IV, which would transform the gameplay in just that: Manoeuvring space marine squads through dungeons. Just checked: It’s called Afterworld, and is a mod for Beyond the Sword. It appears that Firaxis has more experience with the genre than one would think at first. And from the looks of it, they plan to include most of the meta-game features from the original in their version. A wise choice.

There is an idea in the new UFO that I like very much: Vertical base building. In the original, the base layout had one single use: Creating the level if an alien ship attacks you directly. Aliens could only enter through the main elevator and the hangars, which made mostly for samey, H-shaped bases in my case. The screenshots look like There is a single point of entry from above, which could free the rest of the space for actually interesting construction after the entry is secured. So, there is a chance to give adjacent rooms more context than simply raising a global base statistic.
Ok, I notice I will be mostly speculating and wishlisting from here on. I’ll save that after more information is released.

Trolls united

Most of them are probably aliens, anyway

The other evolutionary branch

Just one thing: Please tweak your Art Direction? It’s all looking so shooter bland. Yes, you probably have to follow a newly created brand bible, but really. On some of the worse screenshots, the game looks like an indistinguishable mass of brown overlayed with a screaming UI.
How about adding some more colour? The original worked well with its comic look, heavily inspired by Image Comics. Hey, you could even take it further, and go for the Asian audience (see picture). Please?

Another thought from a developer point of view: Is Firaxis trolling 2K Marin? That is the studio responsible for the UFO Shooter. They are peacefully aligned on the official brand page. But after the 2K boss dismissed strategy games last year as “not contemporary”, I would have completely understood if Firaxis had added a single line to their strategy UFO press reveal: “@cHartmann: ZING!”