Skip to content

Author: Paolo Gambardella

The Difference Between Document and Documentation

Published by Paolo Gambardella on 21/05/2026

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?

Prototypes for Learning

Published by Paolo Gambardella on 20/05/2026

This post was originally written in Italian by Paolo Gambardella. It has been translated by an AI agent and may contain inaccuracies.

Prototypes are one of the areas where game design has evolved enormously over the past few months. New machine learning and automation tools mean everyone can move much faster when building the artefacts we need to learn from — and to help our team learn. That’s a real step forward, but it can amplify a tendency I’ve noticed in some teams: building a prototype that’s too polished and ends up becoming a demo.

A prototype exists to help you learn, to answer questions. A demo exists to convince people, to get a greenlight, to sell. The problem appears when you create something refined enough to look convincing, but too ambiguous to tell you whether you actually learned anything. You end up neither learning nor convincing anyone.

Let me give a concrete example. If this is your first time reading this, you should know I’m a game design consultant specialising in concepting and pre-production for new video games, primarily free-to-play. I run a small studio, and last week my team and I built this prototype using Godot:

  • The project kicked off on Monday with a vision I’d been carrying around for a while, which I then shaped into a vision document
  • My assistant Eduard researched other games and handed me a concept document on Wednesday
  • On Thursday I fed that document to Claude Code and asked it to generate a basic prototype
  • From Friday to Sunday I made small tweaks based on ideas that came to me while I was doing other things.

After handing the result to my assistant, he played it for a whole day and gave me his take. The conversation drifted heavily towards things like “the generated track is monotonous” or “you can’t really collide with the other cars” — all valid concerns from demo stage onwards, but not at this point. The two of us, talking it through, managed to identify the real learning: what we actually like about this prototype. We set it aside, document it, and move on to the next learning phase.

If it had just been me, or if we’d been at a bigger company, we’d probably have also needed to put together a presentation of the learnings to get everyone aligned. That’s how I like to work — but I’ll be honest: the temptation to fix the technical issues or improve the AI of the enemy vehicles was real. Why? Because right now it’s easy. It’s quick.

You can do it, but so can your competitors. The way I see it, the winners are the ones who focus on the right things at the right time. Discernment matters more than ever today. A contact of mine mentioned that App Store review times are getting significantly longer, given the volume of vibe-coded apps now landing in moderators’ queues. If we’re going to wait longer for approval anyway, we might as well be waiting on something genuinely worth shipping.

A Good Era for Game Design

Published by Paolo Gambardella on 19/05/2026

This post was originally written in Italian by Paolo Gambardella. It has been translated by an AI agent and may contain inaccuracies.

During the free-to-play mobile boom, this corner of the games industry was quickly taken over by product management. In a way, that makes sense — the free-to-play business revolves around player acquisition, which means performance marketing. If the cost to acquire a player is lower than what that player spends on average in the game, you’ve got a working business.

So, working as a game designer in those companies very often became a conversation purely grounded in data. I myself repeatedly found myself arguing with my bosses over things we could summarise as: my taste VS the current state of the market. A practical example: if I — as a designer — felt that a certain fantasy needed to be expressed through specific mechanics because I had a hunch it would work, the default response was: “okay, and where have you seen this? In which other games?” Very often it was something that came from a personal experience, or something else entirely. Maybe an app, a film, or an exhibition I’d visited had sparked an idea. Nothing doing — I had to find a way, absolutely, to back it up with data.

And in fact, the designers who built the most successful careers in that sector very often describe themselves as data-driven. They know how to research what’s already there in successful games and reapply it like a mathematical formula to whatever they’re working on. Fair enough — it’s a real skill. But to me, a designer must have both a sense of the business context and a genuine taste. If we’re going to put this much energy into something, we might as well create something new — put something of ourselves into it. People notice when you actually have something to say.

I think this is our moment, right now. This is the moment for designers who want to express their own taste. In my opinion, data-driven design is dead. It was always repetitive, not particularly creative work, but I believe that in the age of AI — where an agent does all of that in far less time and at a fraction of the cost — we’re better off cultivating our own taste instead. Better to watch films, study different kinds of apps, go to exhibitions. Better, in short, to genuinely search for our own voice.

What I believe in — and have always believed in — is data-informed design. Any self-respecting designer should always try to empathise with their players, and there’s no better way to do that than collecting data. But that data shouldn’t dictate our taste, or else we’ll always be offering horses to people who need something new — like selling carriages in Henry Ford’s time. A designer can’t fly blind.

But a game designer needs to have the freedom to create, to bring something genuinely new into the world. Hiring people to repeat formulas is absurd, and I think that practice is destined to disappear — because now we have the right algorithm. One that lets us focus on what truly matters.

Powered by