This post was originally written in Italian by Paolo Gambardella. It has been translated by an AI agent and may contain inaccuracies.
When people talk about game design documents — about design documentation — they usually jump straight to templates and standard formats. In my view, that’s a missed opportunity to look at the bigger picture. Format is just one aspect of one of the five parts of good design documentation.
A few months ago I wrote about the difference between a document and documentation. This post picks up from there: once we’ve established that we’re documenting something concrete, what should the document actually contain?
Five perspectives
To keep things concrete I’ll use a simple example: the boost in a racing game.
Knowledge. First of all, a design document is built around a set of things the game — or the feature in question — should teach players. I’ve talked before about the player experience narrative, which is the story of the game or feature written from the perspective of an enthusiastic player. This helps us identify the components of what we’re describing, and therefore the skill atoms — the individual pieces of knowledge we’re trying to convey. Fun always comes from a process of discovery, much like a creative one: to play is to learn.
For the boost, the skill atoms might be: understanding when the bar is full, discovering that boosting through a corner causes you to lose grip, learning to save it for the final straight. Each of these is a small discovery, and each one needs to be described.
Objectives. Second, the document contains the objectives we have from the game’s perspective. These take the form of specific behaviours we expect from players, and sometimes emotions we want to evoke. You’d typically start from the game pillars (if you have them) and use them to articulate the goal you’re working towards.
For the boost, the objective might be that the player uses it at least once per lap and feels a rush of adrenaline on the straight. A pillar is only useful if it forces you to give something up: if the pillar is “speed”, the document should also say what we’re sacrificing to maintain it — for example, no menus during a race. And if we’re expecting a specific behaviour, we should also write down how we’ll measure it. An objective you can’t observe in a playtest or in the data is just wishful thinking.
Gameplay. Next comes planning the gameplay itself — making the player’s objectives concrete, along with the content, activities, and any strategies they might use to overcome obstacles. This is where you’ll most often find flowcharts, bullet lists, and so on.
This is where format comes into play. How we present the gameplay should serve whoever’s reading it. For the boost, a diagram showing the states (empty, charging, full, active) tells a programmer more than three pages of text, while a table with speeds and durations is more useful to whoever handles balancing. Format is chosen based on the content and the reader, and it can change from section to section.
Systems. A good design document can’t afford to ignore systems. A system is a group of mechanics that, together, teach the player something — which is why I see it as a collection of learning experiences. There are also unplanned dynamics that we can sometimes identify and that end up becoming part of the metagame.
Scott Mercer talks in a short video about how he designed Gruul the Dragonkiller, a boss from World of Warcraft: The Burning Crusade. He wanted to recreate the feeling of musical chairs — when the music stops and everyone scrambles to find a seat. The first mechanic, Shatter, deals damage to players who are near each other, so players learn to spread out. Mercer immediately anticipates an unplanned dynamic: the raid might assign everyone a fixed spot, and all the fun would vanish. So he adds Ground Slam, which flings each player in a random direction and forces them to improvise. Then there’s latency: in 2007 many players were still on dial-up, and everyone saw others in slightly different positions. So he introduces a gradual slowdown, which gives clients time to sync up and, as a bonus, adds tension. Finally, the more players die, the more space there is to spread out, meaning the fight would get easier over time. A steady increase in damage keeps everyone motivated to stay alive.
Each mechanic patches a hole left by the previous one, and each one changes what the player is learning. That’s why, if the feature we’re documenting is part of a larger system — or affects other systems — we need to show we understand the bigger picture and make a genuine attempt to anticipate how it’ll behave. Back to our example: if the boost recharges by collecting items on the track, that also changes how the player chooses their line, and level design needs to know that.
Production. Finally, good design documentation helps resolve design problems and challenges, and guides programmers and artists in building all the assets needed for the feature or game to succeed. For the boost, that means listing visual effects, sounds, and camera movements, and flagging the open questions: what happens if the player activates the boost mid-jump?
Templates have their limits
When we focus too much on the final format, we risk losing sight of the bigger picture and leaving out parts that one template might cover and another might not.
Take the one-pager. It’s great for aligning a team or pitching an idea to a publisher, yet there’s no room in there for systems and their interactions. Many classic GDD templates, on the other hand, have sprawling sections on gameplay and nothing on the knowledge the player needs to acquire. When I choose a format, I already know which of the five parts I’m sacrificing, and I document it somewhere else.
That’s why I use the five parts as a checklist, before I even open a template: knowledge, objectives, gameplay, systems, production. If one is missing, the document has a gap — whatever format it’s in.
