This post was originally written in Italian by Paolo Gambardella. It has been translated by an AI agent and may contain inaccuracies.
One of a game designer’s core responsibilities is writing design documentation. Anyone can write a document, but a designer commits to documentation — and that’s a different thing entirely.
A document holds thoughts, ideas, whatever comes to mind. Documentation, on the other hand, is a specific type of document about something concrete. Research on a competitor game. The results of a playtest. A feature we built and watched in action. A prototype that answered a precise question.
To understand why this distinction gets ignored so often, it helps to think about how knowledge accumulates during game development.
Concept DOCUMENTS
At the start of a project, almost everything is uncertain.
- Constraints | There are things we already know: the target platform, the genre, maybe the budget.
- Frontiers | There are questions we know we need to answer: how the core loop works, how long a typical session lasts.
- Risks | There are the things we don’t yet know we don’t know. Design problems that only surface when a player has a controller in their hands. Interactions between systems that seemed obvious on paper and turn out to be a disaster in practice. Assumptions nobody ever questioned because they seemed too obvious to bother with.
A concept document lives almost entirely in that third layer. It isn’t documentation — it’s a snapshot of the team’s imagination at a specific moment in time.
Game Design DOCUMENTATION
Real documentation comes later. After we’ve prototyped and discovered that the mechanic we thought was brilliant doesn’t work the way we expected. After we’ve looked at how another game solved the same problem. After we’ve tested and observed. At that point, we actually have something worth documenting.
Documents and Documentation
A document serves a temporary purpose. Meeting notes are a document. A concept doc is a document. A list of ideas scribbled down before a brainstorming session is a document. These are valid, necessary working tools, and they have a natural lifespan: they’re useful now, then they become history.
Documentation, on the other hand, is built to last.
- It must be clear to someone who wasn’t in that meeting.
- It must be practical — a reference you can actually use, not just read.
- It must inspire whoever reads it six months later, when the initial enthusiasm has cooled and people need something concrete to hold on to.
- And it must be inviting: not as an aesthetic exercise, but because if nobody opens a document, that document might as well not exist. I follow this formula: 60% of the space should be taken up by visual elements (diagrams, images, video…). 30% by data and tables. 10% text. Documentation isn’t a treatise or a novel to be read cover to cover!
Not every document is documentation, and a project will call for various kinds of document. But your team needs documentation.
What real documentation looks like
Good design documentation answers a handful of questions unambiguously: what is this game? Why is it interesting? What’s the fantasy — the emotional promise it makes to the player? What are the core features — not all the features, just the ones that define the product’s identity? How exactly does this system work? And enough production context to make the document actionable.
There’s a principle I find particularly useful here: if a team can’t explain their game in a clear, compressed way, the design probably isn’t clear enough yet. The clarity of the documentation reflects the clarity of the thinking. A dense document, packed with sections and subsections trying to cover every eventuality, is often a signal that we don’t yet know enough to be documenting.
And that brings us back to rule number one. If you don’t yet have something concrete to document, maybe it’s not the right moment to write documentation. It’s the moment to do research. To build a prototype. To test. To answer the questions you don’t know you have yet. To learn and discover.
Does this document something that exists, or something we want to build?
