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.

Fighting graphs

Although fans argue about build orders

Not an RTS

Many strategy games are resource battles that can be summarized as ascending or descending graphs. Fighting against the numbers is not fun stressful.

Picture a typical session of your favourite video strategy game. It is most likely one of two things: either a constant click-fest or a long, drawn out affair until one final battle after which the defeated player quits the game. I do not like the first version, since most of the time I play to relax. And the second one is problematic on several levels. As you can see from last week’s entry, I like to keep players in the game. The long build-up does that, but for a long an uneventful time, after which you lose everything without a chance to come back.

It’s all in the numbers. The deciding numbers in the first scenario are Actions Per Minute, while the second scenario is decided by Resources Per Minute. Both are systemic to either Real-time- or Turn-Based Strategy Games. For the record, I put the ANNO games into the second category because of their long playtime and many delayed effects. So, if you ever wondered why the series is such a bad RTS: That’s why. It is not designed to be one.

Ascending strategy

Looks like a close fight

Epic battle

Back to the numbers: Ascending graphs are used for games with a build-up phase. This phase transforms the available resources of the map into combat resources that can be used against opponents. Usually, all players begin with the exact same resource setup and means to transform them. Tactics is applied when it comes to timing and positioning.  You can defeat a more advanced opponent by refusing to go heads on and harass him down to your resource level. But you have to invest lots of actions and good timing to get that down right.

What it boils down for many strategy games, or at least lazy gamers, is: Stacks of Doom. Be it the one undefeatable uber-hero in Heroes of Might & Magic, the single killer-stack in Civilization, or all your warships in ANNO. It all ends in one single confrontation that decides the war. Far more relaxing than constant tactics, but not guaranteed to satisfy.

Descending strategy

An army had to die to bring you this screenshot

Gratuitous battle

On the other end are descending graphs for games that skip the build-up. These are usually more focused on tactics and army composition. Most use point values for units to make sure all players start with the same resource strength. Victory goes to the player with more units standing at the end. This puts the whole gameplay around one large negative loop: Whatever you do, you will lose resources, and they are not coming back.

These make for some interesting matches. Both players can see what they are up against and plan accordingly. Yes, there is still a breaking point where one side decidedly got the upper hand. But at least to me, surrender in these games comes more easily and with more satisfaction for the winner. Maybe that is because of the absolute vision and battle state knowledge (Note to self: check hypothesis with next concept). There are a lot of tabletop examples like Warhammer, Battletech or most famously, Chess. But unfortunately, few videogame versions.

My point being…

The pieces get thrown around only after the game is finished

Some Euro Game

Ok, you got me. Nothing new here. Just wanted to express my need to boil down games to systemic graphs and numbers. Because these are necessary to answer some of the questions I ask myself when analysing different games: What type of resource structure does it have? What are the deciding factors for victory? Why do players quit minutes after starting a game session if they did not have a perfect start? What can I do to keep players in the game and offer both, the winning and the losing player a fun experience?

Here are some common answers to the last one:

  • Rubberbanding: Give benefits to the slower and handicap the faster players. Can be either obvious or quietly running in the background.
  • Different victory conditions: It does not matter if one player ascends faster than the other if both work on different graphs.
  • Wait with the scoring: Usual solution in Euro games. Players learn who won only after the final tally of points.

A game should not rely on one dominant stack-of-doom strategy. That includes making other strategies both viable to win and easier to employ, without giving players carpal tunnel syndrome. And finally, there should be more PC games with descending strategies. Go for it!