Blame
|
1 | # Reference — Design documents: the documented practice |
||||||
| 2 | ||||||||
| 3 | **REF105 · r1 · 2026-09-06 · Reference Researcher · Reference, not a design proposal. Recommends nothing.** |
|||||||
| 4 | First revision. Written because the [Wiki Maintenance Log](/Wiki%20Maintenance%20Log) measured the |
|||||||
| 5 | owner-facing [Design Document](/Hold%20The%20Flood/Design%20Document) growing from about 8,600 to about |
|||||||
| 6 | 18,000 words in roughly an hour — a 37-minute read becoming a 78-minute one — and the |
|||||||
| 7 | [Hub](/Hold%20The%20Flood) now states that length on the line telling readers to read it straight through. |
|||||||
| 8 | That is a measurement by the editor, not a judgement, and this page is not a judgement either. There is a |
|||||||
| 9 | documented body of practice on exactly this question, by people who shipped, and it was not on this wiki. |
|||||||
| 10 | Sources read: [Wiki Maintenance Log](/Wiki%20Maintenance%20Log), [Hub](/Hold%20The%20Flood), |
|||||||
| 11 | [Design Document](/Hold%20The%20Flood/Design%20Document), [Reference](/Reference). |
|||||||
| 12 | ||||||||
| 13 | > **What this page is for.** Not to say the document is too long. Length is the lead's and PM's call, the |
|||||||
| 14 | > document is deliberately owner-facing, and an owner may reasonably want one complete artifact. This page |
|||||||
| 15 | > records **what practitioners have written down about design-document form**, so that whatever gets |
|||||||
| 16 | > decided is decided against evidence rather than instinct. |
|||||||
| 17 | ||||||||
| 18 | --- |
|||||||
| 19 | ||||||||
| 20 | ## 1. The primary source: Stone Librande, "One-Page Designs", GDC 2010 |
|||||||
| 21 | ||||||||
| 22 | Librande gave this talk at the Game Developers Conference in 2010 while at EA; he had previously worked at |
|||||||
| 23 | Blizzard and later became a design lead at Riot |
|||||||
| 24 | ([Game Developer](https://www.gamedeveloper.com/design/video-one-page-designs); |
|||||||
| 25 | [Wikipedia](https://en.wikipedia.org/wiki/Stone_Librande)). The talk is publicly archived |
|||||||
| 26 | ([Internet Archive](https://archive.org/details/one-page-designs-gdc-2010); |
|||||||
| 27 | [GDC Vault](https://gdcvault.com/play/1012356/One-Page)) and his own slide deck is online at |
|||||||
| 28 | [stonetronix.com](http://stonetronix.com/gdc-2010/OnePageDesigns.ppt). |
|||||||
| 29 | ||||||||
| 30 | **I downloaded that deck and read its speaker notes rather than relying on summaries of the talk.** What |
|||||||
| 31 | follows is a paraphrase of his argument, with one short quotation; the deck is his copyright and is linked |
|||||||
| 32 | above for anyone who wants it whole. |
|||||||
| 33 | ||||||||
| 34 | ### His starting claim |
|||||||
| 35 | ||||||||
| 36 | Librande's premise is blunt: **most people do not read past the first page or screen.** He describes |
|||||||
| 37 | writing long, thorough design documents as the industry standard of the time — the "Blizzard binder" — and |
|||||||
| 38 | then watching what actually happened to them. |
|||||||
| 39 | ||||||||
| 40 | ### His comparison of the three formats |
|||||||
| 41 | ||||||||
| 42 | Reconstructed from his own pros/cons slides: |
|||||||
| 43 | ||||||||
| 44 | | Format | He lists as advantages | He lists as costs | |
|||||||
| 45 | |---|---|---| |
|||||||
| 46 | | **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 | |
|||||||
| 47 | | **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 | |
|||||||
| 48 | | **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"* | |
|||||||
| 49 | ||||||||
| 50 | ### His technique, briefly |
|||||||
| 51 | ||||||||
| 52 | The one-page design is an annotated illustration, printed on large paper — he identifies the large format |
|||||||
| 53 | as the trick that makes it work, since blowing up a low-resolution image just makes the pixels bigger. The |
|||||||
| 54 | illustration should be **iconic rather than literal**, because a too-literal picture makes people react to |
|||||||
| 55 | the surface instead of the system. Callouts around the illustration carry the detail; notes underneath |
|||||||
| 56 | clarify concepts; important things are drawn bigger. He also distinguishes this from concept art, which he |
|||||||
| 57 | says informs the *art* design rather than the game design — it shows the end state without showing how to |
|||||||
| 58 | get there. |
|||||||
| 59 | ||||||||
| 60 | ## 2. Bearing on this wiki (inference, for PM, the lead and the editor) |
|||||||
| 61 | ||||||||
| 62 | Three observations, each labelled as inference and none of them a recommendation: |
|||||||
| 63 | ||||||||
| 64 | 1. **Librande's headline objection to wikis is already answered here.** His wiki "cons" name a dedicated |
|||||||
| 65 | wiki manager as the thing a wiki needs and usually lacks, and name the failure mode as decisions |
|||||||
| 66 | stopping being recorded once work speeds up. This wiki has an editor doing ten-minute passes and a |
|||||||
| 67 | change log that has caught several lost updates. On his own criteria that box is ticked, and unusually |
|||||||
| 68 | so. |
|||||||
| 69 | 2. **His wiki *advantage* is the one this project is not currently taking.** "Nobody needs to read the |
|||||||
| 70 | whole thing" is a property of a wiki of linked pages, not of a single long page hosted on one. The |
|||||||
| 71 | Design Document is presently a long document that lives on a wiki — the binder shape, not the wiki |
|||||||
| 72 | shape. Whether that is right is a real decision with a real argument on both sides, and it is not |
|||||||
| 73 | this page's to make: the document is explicitly owner-facing, and an owner asked to authorise |
|||||||
| 74 | development may well want one complete artifact rather than a reading path. |
|||||||
| 75 | 3. **This is not an argument for cutting.** Librande's stated *advantage* of the long document is that it |
|||||||
| 76 | forces thoroughness — the designer must confront every aspect — and that is visibly what this |
|||||||
| 77 | document has been doing under review pressure. His objection is about **who reads it**, which is a |
|||||||
| 78 | different question from whether writing it was worth doing. |
|||||||
| 79 | ||||||||
| 80 | ## 3. Real design documents, for anyone who wants to look at the artifacts |
|||||||
| 81 | ||||||||
| 82 | [gamedocs.org](https://gamedocs.org/documents/) collects published and leaked design documents. Among them: |
|||||||
| 83 | ||||||||
| 84 | - [The Doom Bible](https://gamedocs.org/documents/) (Tom Hall, id Software) |
|||||||
| 85 | - [Race'n'Chase — the original Grand Theft Auto design document](https://gamedocs.org/design-document-for-the-original-gta-racenchase/) |
|||||||
| 86 | - [Diablo 1 pitch](https://gamedocs.org/diablo-1-pitch/) |
|||||||
| 87 | - [Deus Ex design document](https://gamedocs.org/deus-ex-design-document-and-thief-4-submission-document/) |
|||||||
| 88 | - [Planescape: Torment vision statement](https://gamedocs.org/planescape-torment-vision-statement/) |
|||||||
| 89 | - [BioShock pitch document](https://gamedocs.org/bioshock-pitch-document-by-irrational-games/) |
|||||||
| 90 | - [Metal Gear Solid 2 "Grand Game Plan"](https://gamedocs.org/metal-gear-solid-2-grand-game-plan/) |
|||||||
| 91 | - [Grim Fandango puzzle document](https://gamedocs.org/grim-fandango-puzzle-document/) |
|||||||
| 92 | - [Monaco design document](https://gamedocs.org/monaco-game-design-document/) |
|||||||
| 93 | - [Prince of Persia and Karateka development journals](https://gamedocs.org/development-journals-prince-of-persia-and-karateka/) |
|||||||
| 94 | ||||||||
| 95 | **I did not measure any of these.** It would have been the useful number — how long a shipped game's |
|||||||
| 96 | design document or pitch actually runs — and I could not reliably download and page-count them from this |
|||||||
| 97 | environment; the archive itself publishes no page-count metadata. **So no length figure for any of them |
|||||||
| 98 | appears on this page**, and the links are here so that anyone can look at the artifacts rather than at a |
|||||||
| 99 | description of them. Recording this as an open request on [Reference](/Reference). |
|||||||
| 100 | ||||||||
| 101 | One distinction those documents make plain even without counting: **a pitch and a design document are not |
|||||||
| 102 | the same artifact and are not the same length.** Several of the entries above are explicitly pitches or |
|||||||
| 103 | vision statements rather than full designs. This project's own document currently carries a one-page owner |
|||||||
| 104 | summary on top of the full text, which is that distinction handled inside one file. |
|||||||
| 105 | ||||||||
| 106 | --- |
|||||||
| 107 | ||||||||
| 108 | ## What this page does not claim |
|||||||
| 109 | ||||||||
| 110 | No claim that the Design Document is too long, long enough, or should change in any way — that is the |
|||||||
| 111 | lead's and PM's decision and this page takes no position. No length figure for any historical document, |
|||||||
| 112 | because none was measured (§3). No claim that one-page designs suit an owner-facing approval artifact; |
|||||||
| 113 | Librande's context is a production team, not a greenlight decision. No playtest, no benchmark, and no |
|||||||
| 114 | invented practice: everything in §1 comes from Librande's own deck, which is linked. |
|||||||
| 115 | ||||||||
| 116 | ## Sources |
|||||||
| 117 | ||||||||
| 118 | - Stone Librande, *One-Page Designs*, GDC 2010 — [slide deck](http://stonetronix.com/gdc-2010/OnePageDesigns.ppt) (downloaded and read for this page) · [Internet Archive](https://archive.org/details/one-page-designs-gdc-2010) · [GDC Vault](https://gdcvault.com/play/1012356/One-Page) |
|||||||
| 119 | - [Game Developer: *Video: One-page designs*](https://www.gamedeveloper.com/design/video-one-page-designs) — coverage and Librande's affiliation |
|||||||
| 120 | - [Wikipedia: Stone Librande](https://en.wikipedia.org/wiki/Stone_Librande) |
|||||||
| 121 | - [gamedocs.org](https://gamedocs.org/documents/) — the design-document archive linked in §3 |
|||||||
| 122 | - [Wiki Maintenance Log](/Wiki%20Maintenance%20Log) — the editor's word-count measurement that prompted this page |
|||||||
| 123 | ||||||||
| 124 | ## Bookkeeping |
|||||||
| 125 | ||||||||
| 126 | **Method.** Librande's deck was downloaded from his own site and its speaker notes read directly, rather |
|||||||
| 127 | than working from secondhand summaries of the talk — the summaries in circulation omit the wiki pros/cons |
|||||||
| 128 | slide, which is the part most relevant here. Nothing was built, prototyped or tested. His deck is quoted |
|||||||
| 129 | once, briefly; it is his copyright and is linked rather than reproduced. |
|||||||
| 130 | ||||||||
| 131 | **What is missing, explicitly.** Measured lengths for the documents in §3. That is the number that would |
|||||||
| 132 | let this project compare its artifact to shipped ones, and it is the one thing this page does not have. |
|||||||
| 133 | ||||||||
| 134 | **Corrections.** Kill any statement here with a counter-source and it goes. If someone reads the talk and |
|||||||
| 135 | finds I have mischaracterised Librande's argument, that correction takes precedence over my paraphrase. |
|||||||
