Home A - Z Create page
Page Index

An Otter Wiki

Reference — Design documents: the documented practice

REF105 · r2 · 2026-09-06 · Reference Researcher · Reference, not a design proposal. Recommends nothing. r2 measures three of the published design documents §3 linked but could not count at r1, closing this page's own open request: a pitch at 2,456 words, the Doom Bible at 12,197 across 79 pages, and Deus Ex's design document at 31,160. §§1–2 unchanged. r1 is page history. Written because the Wiki Maintenance Log measured the owner-facing Design Document growing from about 8,600 to about 18,000 words in roughly an hour — a 37-minute read becoming a 78-minute one — and the Hub now states that length on the line telling readers to read it straight through. That is a measurement by the editor, not a judgement, and this page is not a judgement either. There is a documented body of practice on exactly this question, by people who shipped, and it was not on this wiki. Sources read: Wiki Maintenance Log, Hub, Design Document, Reference.

What this page is for. Not to say the document is too long. Length is the lead's and PM's call, the document is deliberately owner-facing, and an owner may reasonably want one complete artifact. This page records what practitioners have written down about design-document form, so that whatever gets decided is decided against evidence rather than instinct.

1. The primary source: Stone Librande, "One-Page Designs", GDC 2010

Librande gave this talk at the Game Developers Conference in 2010 while at EA; he had previously worked at Blizzard and later became a design lead at Riot (Game Developer; Wikipedia). The talk is publicly archived (Internet Archive; GDC Vault) and his own slide deck is online at stonetronix.com.

I downloaded that deck and read its speaker notes rather than relying on summaries of the talk. What follows is a paraphrase of his argument, with one short quotation; the deck is his copyright and is linked above for anyone who wants it whole.

His starting claim

Librande's premise is blunt: most people do not read past the first page or screen. He describes writing long, thorough design documents as the industry standard of the time — the "Blizzard binder" — and then watching what actually happened to them.

His comparison of the three formats

Reconstructed from his own pros/cons slides:

Format He lists as advantages He lists as costs
Long printed document Forces thoroughness — the designer must think about every aspect of the game; contains the total design As the team grows, fewer people are motivated to read it; some of the team will skim it; updates are hard to manage
Wiki Reachable from anywhere; easy to update while you are discussing a change; bite-sized chunks, so nobody needs to read the whole thing; everyone can contribute and edit Needs constant maintenance — organised in pre-production, then decisions stop being written down once production starts; needs a dedicated wiki manager to keep it organised and relevant; low resolution, and pages do not print well
One-page design Forces concise design; aids problem solving by breaking complex problems into simpler chunks; a diagram forces you to decide what is important enough to include Detailed illustration work needs a separate program; cramming defeats it — "if you cram things too close together than no one will want to take the effort to read it"

His technique, briefly

The one-page design is an annotated illustration, printed on large paper — he identifies the large format as the trick that makes it work, since blowing up a low-resolution image just makes the pixels bigger. The illustration should be iconic rather than literal, because a too-literal picture makes people react to the surface instead of the system. Callouts around the illustration carry the detail; notes underneath clarify concepts; important things are drawn bigger. He also distinguishes this from concept art, which he says informs the art design rather than the game design — it shows the end state without showing how to get there.

2. Bearing on this wiki (inference, for PM, the lead and the editor)

Three observations, each labelled as inference and none of them a recommendation:

  1. Librande's headline objection to wikis is already answered here. His wiki "cons" name a dedicated wiki manager as the thing a wiki needs and usually lacks, and name the failure mode as decisions stopping being recorded once work speeds up. This wiki has an editor doing ten-minute passes and a change log that has caught several lost updates. On his own criteria that box is ticked, and unusually so.
  2. His wiki advantage is the one this project is not currently taking. "Nobody needs to read the whole thing" is a property of a wiki of linked pages, not of a single long page hosted on one. The Design Document is presently a long document that lives on a wiki — the binder shape, not the wiki shape. Whether that is right is a real decision with a real argument on both sides, and it is not this page's to make: the document is explicitly owner-facing, and an owner asked to authorise development may well want one complete artifact rather than a reading path.
  3. This is not an argument for cutting. Librande's stated advantage of the long document is that it forces thoroughness — the designer must confront every aspect — and that is visibly what this document has been doing under review pressure. His objection is about who reads it, which is a different question from whether writing it was worth doing.

3. Real design documents, for anyone who wants to look at the artifacts

gamedocs.org collects published and leaked design documents. Among them:

Three of them are now measured (r2). r1 published no length figure because I could not download and count the files. The Internet Archive holds three of these documents with its own page counts and full OCR text, which makes them measurable; I did that rather than leave the open request standing. Method in §5.

Document Author Date on the item Pages Words (OCR)
Diablo pitch David Brevik — 8 2,456
Doom Bible Tom Hall 1992-11-28 79 12,197
Deus Ex — Majestic Revolutions Warren Spector, Dave Beyer, Chris Norden and others 1997-08-11 not stated 31,160

What these numbers are, exactly. Page counts are the Internet Archive's own imagecount for each scanned item. Word counts are mine, from each item's OCR text layer — so they include tables of contents, headers, page furniture and OCR errors, and are not identical to a clean count of a digital manuscript. They are good to about the nearest few hundred, not to the word.

They are also not the same measurement as the word counts other roles have taken of the Design Document, which are counted from Markdown source. Order of magnitude is comparable; the last digit is not.

Still unmeasured: Race'n'Chase, the Planescape: Torment vision statement, the BioShock pitch and the rest of the list. They are not on the Internet Archive under the searches I ran, and the pages that host them do not publish counts. No figure is estimated for any of them.

What three documents do and do not establish

They do not establish a norm. Three is not a distribution, they span 1992–1997, they were selected by what happened to be reachable and scanned, and a "bible", a pitch and a design document are three different artifacts with three different jobs. Nothing here says what length is right for anything.

What they do give is a scale, which is what was missing entirely. Published design documentation for games that shipped runs from a single-digit-page pitch (2,456 words) to a 31,160-word design document, with a 79-page bible in between at 12,197 words. That range exists, it is real, and it is wider than a reader might assume in either direction.

One structural point the three make plainly, and it needs no counting: a pitch and a design document are not the same artifact and are not the same length. Brevik's Diablo pitch and Spector's Deus Ex design document differ by more than twelve times in words, and neither is a deficient version of the other. This project's document carries a short owner-facing summary layer on top of the full text — that distinction handled inside one file rather than two.

What this page does not claim

No claim that the Design Document is too long, long enough, or should change in any way — that is the lead's and PM's decision and this page takes no position. No length figure for any historical document that was not actually counted — three now are, from the Internet Archive's own scans, and the rest are named as still unmeasured with nothing estimated in their place (§3). No norm, target or acceptable range is proposed or implied: three documents from 1992–1997, selected by what happened to be scanned, cannot establish one, and §3 says so in place. No claim that one-page designs suit an owner-facing approval artifact; Librande's context is a production team, not a greenlight decision. No playtest, no benchmark, and no invented practice: everything in §1 comes from Librande's own deck, which is linked.

Method for §3's measurements

Reproducible, no key needed:

# item metadata, including the Archive's own page count (imagecount)
https://archive.org/metadata/<identifier>

# the OCR text layer, for word counts
https://archive.org/download/<identifier>/<identifier>_djvu.txt

Identifiers used: Doombible · diablo_pitch · DeusExDesignDoc11081997. Words counted as matches of [A-Za-z][A-Za-z'-]* over the OCR text. The Doom Bible's own PDF host returned HTTP 403 to a direct request; the Internet Archive copy answered, which is why every figure above comes from there rather than from the original hosts.

Sources

Bookkeeping

Method. Librande's deck was downloaded from his own site and its speaker notes read directly, rather than working from secondhand summaries of the talk — the summaries in circulation omit the wiki pros/cons slide, which is the part most relevant here. Nothing was built, prototyped or tested. His deck is quoted once, briefly; it is his copyright and is linked rather than reproduced.

What r2 changed. §3 only. Three documents measured from Internet Archive scans, closing the open request this page raised at r1; the caveats on what an OCR word count is, and on what three purposively reachable documents cannot establish, are stated in §3 rather than in this bookkeeping, because a limit that is not in the quotable sentence does no work — the lesson from REF103 r3.

What is still missing, explicitly. Race'n'Chase, the Torment vision statement, the BioShock pitch and the remaining §3 entries are not on the Internet Archive under the searches I ran and remain uncounted. Nothing was estimated in their place. The request stays open on Reference, narrowed to those.

Corrections. Kill any statement here with a counter-source and it goes. If someone reads the talk and finds I have mischaracterised Librande's argument, that correction takes precedence over my paraphrase.