Design docs nobody reads

I have written a design document for every project I have started, and I could not tell you what is in most of them. Week one it is the most important file in the repo. By week six it is wrong. Somewhere around week twelve I make a decision that contradicts it and nobody notices, least of all me.

The usual diagnosis is discipline. Keep it updated. I believed that for a while, then I went looking for a better template and found the same forty-section skeleton reprinted across thirty content-farm blogs, all citing each other and none citing a game.

So I went and read the real ones instead. There are far more in public than I expected: leaked, released by their authors, or donated to preservation archives. I ended up with 157 files, about 436MB, covering roughly 65 games from the mid-eighties to the mid-2010s. A sample of what is in there:

• The Doom Bible - Tom Hall, 1992, 79 pages, and mostly thrown away
• GTA, back when it was called Race’n’Chase
• Deus Ex’s original design document, filed under the working title Majestic Revolutions
• the Diablo and BioShock pitches
• Grim Fandango’s puzzle document, which is the whole puzzle dependency graph
• Planescape: Torment’s vision statement
• Dirty Bomb - a complete modern GDD, 315 pages of it

Then I counted what was actually in them, which turned out to be the interesting part.

Where these came from

Three places did nearly all the work: a 211MB zip from splatterladder holding 150 files, the Video Game History Foundation’s design doc archive, and gamedevs.org, where the design documents sit at the very top of the page above a mountain of graphics papers.

Counting only works on text, and about a third of these files do not have any. Somebody photocopied a binder in 1994 and the scan is what survived, so there is nothing in the PDF but pixels. I can read them with my eyes, a script cannot, and there is no OCR pass available for those particular ones. 36 of 83 PDFs are in that state. It hurts most for the LucasArts and Sierra material and for the Diablo and BioShock pitches, which are lovely and completely invisible to a word count.

That leaves 43 documents with real text in them: 24 full design documents, 17 pitch or vision documents, and 2 single-system specs, dated 1992 to 2017. Every number below comes from those.

The counting itself is crude on purpose. I pull heading-shaped lines out of the extracted text and match them against a fixed list of concepts, so a document that discusses audio for three pages without ever putting the word in a heading counts as having no audio section. Treat every percentage as a floor.

One document nearly got me. There is a silent-hill-design-document.pdf going round that looks like the platonic ideal of a Konami GDD: sixty pages, every section in the right order, immaculate. It sat in my pile for a while before I noticed the bibliography.

It is a university assignment. Written years after the fact, about Silent Hill 2, with a student’s name in every one of the sixty page footers. It follows Tim Ryan’s 1999 template so faithfully that it reads more like a real design document than most of the real design documents do, which is exactly why it fooled me. Whoever you were: you did a genuinely good job and you cost me an afternoon. It is out of the numbers, and it is still the cleanest worked example of that template I have found.

UI is the most universal section. Gameplay is not

Across the 24 full design documents:

Rate	Section
96%	UI / HUD / menus
92%	Audio / sound / music
88%	Levels / missions
88%	Weapons / items / inventory
62%	Core gameplay
46%	Combat

I expected core gameplay at the top. It is not close. UI beats it 96% to 62%, and audio outranks combat two to one.

Once you see why, it stops being surprising. UI is where a design stops being an opinion. “Fast, responsive combat” needs no spec and blocks nobody. A health meter needs a position, a state list and an art request, and until somebody writes those down there is an artist sitting there unable to start. Sections survive into documents in proportion to how badly somebody downstream is stuck without them.

Core gameplay scores low for the opposite reason. It is not missing, it is the whole document. It only gets its own heading when a project is big enough to need a named home for how the game feels second to second, which here means Dirty Bomb, Deus Ex, and a cancelled Apocalypse Now adaptation.

That reframed the whole thing for me. A design document is not a description of the game. It is a queue of unblockings, written in the order people got stuck.

A pitch is not a short GDD

The other thing the numbers are unambiguous about. Same 44 sections, split into the 24 full design documents and the 17 pitch and vision documents:

Section	Full GDD	Pitch	Δ
UI / HUD / menus	96%	24%	+72
Table of contents	83%	18%	+66
Camera	38%	0%	+38
Core gameplay	62%	65%	-2
Multiplayer	62%	65%	-2
Vision / pillars	29%	35%	-6
High concept / logline	8%	24%	-15

Read the bottom half first. Core gameplay, multiplayer and vision show up at the same rate in a four-page pitch and a 315-page GDD. Those three are the irreducible content. Everything above them is elaboration a pitch simply does not do, and the only things a pitch has more of are the logline and the risk statement.

Put plainly, they are two different documents answering two different questions.

A pitch answers “should this exist”. Its reader is deciding whether to fund you, hire you, or care. It needs a logline, the core gameplay, the vision, and a straight line about the biggest thing that could go wrong. It does not need a table of contents, it does not need your menu flow, and not one pitch in this set describes a camera.

A design document answers “what exactly gets built”. Its reader is someone about to make an asset, a system or a level, and they need to not have to ask you. That is where the UI, the item lists, the controls, the audio, the level breakdowns and the flow diagrams live, and it is why those sections jump forty to seventy points between the two formats.

So the pitch is not a first draft of the design document, and expanding one into the other is a category error. I had been doing exactly that for years, which is probably why my documents always felt like they were arguing with a reader who had already left the room.

Four things almost nobody wrote down

Risk: 0% of the design documents. Not one. It appears in 12% of pitches, because a pitch has to get ahead of the obvious objection. Once the money is in, nobody writes down what might go wrong.

Version history: 4%. One document out of 24 keeps a real changelog, and it is Double Fine’s Stacking. Every template in the literature demands one. Chris Taylor’s opens with Design History. Chris Swain’s says outright that a design document “is a continuously changing reference tool”. In practice these were written, delivered, and abandoned, which is precisely the complaint that wrecked the format’s reputation.

How anyone would know if the design worked. Nothing here specifies a playtest plan, a metric, or a success condition. Not even Dirty Bomb, a live multiplayer game with 315 pages to play with.

Accessibility, in the disability sense: zero. I searched for the words rather than the heading, so this is not a detection artefact. The three apparent hits are false friends: one is about a track editor’s difficulty ramp, one is a localisation table, one is a field on a character sheet. The concept postdates almost everything in the folder. These teams were not refusing, it had not arrived yet. It is the one absence I would expect a modern version of this collection to close.

The documents that ignore the template

This is the part I did not expect to enjoy. The best documents here are not the ones that follow the structure, they are the ones that visibly stopped caring about it.

What Remains of Edith Finch is five sections long. Synopsis, Underwater Stories, Other Stories, Guest Stories, Tone. No feature list, no mechanics section, no platform, no market analysis. That is the entire document, and it is correct, because a list of the stories and how it should feel is genuinely what that game is.

The Doom Bible opens on command line parameters, before any design at all. It contains a press release, a calendar, a list of known bugs, a section called Random Notes, and an appendix titled “Random Extremely Important Info Too Small to Rate Having Its Own Section”. It is one person’s working notebook that never pretended to be a deliverable, and it invented a device I have quietly stolen: every episode gets a Unique Bits section, which is the per-episode budget for one memorable thing.

Planescape: Torment’s vision document has a section called Da Fucking Plot and another that is just “357 Bullet Points”. It also does something I have seen nowhere else: it carries a Team Vision Statement separately from the game vision. What the team wants to become, kept distinct from what the game is. It is profane, funny, aimed squarely at its own studio, and it is the only one of these with an unmistakable author.

The Sierra adventures are not design documents at all. Leisure Suit Larry 7, Freddy Pharkas and Torin’s Passage are screenplays. Acts, then rooms, each room listing objects found here and objects used here, with camera direction written in film language. Close-up on Torin, fade to black. If you are documenting a narrative-first game, that tradition fits better than any GDD template is going to.

And then there is Claw, from Monolith, which specifies the CD insert, the registration card, the manual, the cheat codes, and states that the game is “primarily targeted at humans ages 8-30”. Good to have the species narrowed down.

Six documents from Icon Games share one template, and reading them back to back makes something uncomfortable visible. Their sections are Concept Suitability, Visual Appeal, Audio Experience, Innovation, Game Modes, Rewards and Unlockables, Longevity and Replay Appeal, Learning Curve. Every heading is a reassurance aimed at a publisher rather than a description of a game. That is what a design document looks like when its real job is getting a contract signed, and I suspect it is what a fair number of templates are quietly optimised for.

What I steal from them

Four things that changed my own documents.

Bungie’s Halo 3 HUD spec is the most disciplined document in the folder, and it is not a GDD. Section one, before the overview, is Open Issues. The overview then carries an explicit Document Non-goals, a Related Specs list, and a real Document History. Open issues first is the move I would recommend to anybody: what is still undecided is the most valuable thing on page one, and the first thing to rot if you bury it.

One repeating template per system beats one clever structure. Dirty Bomb runs OVERVIEW, GOALS, USER STORIES for every system, 47 times over. Goals are written as intent, so they survive the implementation changing. User stories are in the player’s voice. It is the only reason 315 pages is navigable, and why any section of it can be read on its own. After 130 pages of detail it also ships one-page summaries of all 22 characters, which is the long form and the one-page design in the same binder instead of arguing with each other.

Put systems in a schema, not prose. Deus Ex describes every weapon against a fixed vocabulary: damage from very high down to low, accuracy, clip capacity, and a detectability field with exactly three values. Earth & Beyond goes further and ships the actual damage equations. “The shotgun is powerful at close range” cannot be balanced. A table can. This is the clearest quality divider in the whole pile.

Name your mechanics. Score Chores. Doll Splitting. Unique Bits. Bread Crumbs System. A named thing can be discussed, scheduled and cut. An unnamed one gets rebuilt three times because two people meant different things by it.

Worth reading alongside all this: Tim Ryan’s 1999 anatomy of a design document, ancestor of every template on the internet, best read as history since it wants the design signed off “with no expectations on being able to make changes”. Then Stone Librande’s One-Page Designs, whose argument is that nobody reads long documents and wikis do not fix it, because chopping a design into linked pages destroys the relationships between the pieces, which is most of what the design was. Then the rejections: Jagex on the death of the GDD, and an agile take that refuses to prescribe a format at all and asks only for problem domain, solution and rationale, at a standard it calls Just Barely Good Enough. Cerny’s Method is the process all of that sits inside.

They disagree less than they look. Ryan’s list of what eventually has to be decided is still right and still complete. What the others reject is writing it all up front, in one lump, and calling it final.

What I do now

Open issues at the top, because that is the section I actually reread. Constraints as numbers, because almost every argument three months in turns out to be an argument about one of them. A no list with reasons, since scope creep always arrives dressed as a new idea rather than a rejected one. And one repeating block per system, instead of a structure I invent fresh each time and then abandon.

Everything else lives closer to the work. Stats in the data files, UI in the prototype, decisions in a dated log.

I did build a generator off the back of all this counting, which spits out a starting document weighted by what these documents actually contain rather than what the templates claim.

None of this scales to a fifty-person studio and I am not going to pretend otherwise. But the thing I keep coming back to is Edith Finch’s five sections. Every document here that I would call good is shaped like its own game, and every one that felt dead was shaped like a template. That was never a discipline problem. I had just been filling in somebody else’s form.