• Ray

5 Tips for Writing Great Design Docs


When I first started writing design docs over a decade ago, they were disorganized, littered with weak language, and crammed with blocks of text so impenetrable to the discerning eye that they might have actually shielded a ring-wearing Frodo from Sauron’s gaze.


Compare this bird’s-eye view of a page from one of my first designs with a page from a design I wrote four years later:

Who sees the page on the left and doesn’t wince? It’s almost as friendly as a tome of tax codes. The page on the right, on the other hand, is inviting – it’s colorful, organized, and appropriately sparse. The first problem any designer must overcome is getting their team to want to read a design. The second problem is presenting the information in a useful format for implementation. In this article, I’m going to share five tips I’ve learned that led to my current design doc style – a style which I’ve considered a success ever since developers who have moved onto other projects told me they missed this format. 


1. Always Start with Design Goals


If you’re designing a feature, your developers need to know what its purpose is. It’s context for the rest of the design, and not only informs the developers how to read each aspect, but also helps them provide better suggestions for improvements.

More importantly, the goals are for you, the designer. Writing 3-5 goals forces you to get to the heart of a design’s importance. Once you’ve written them, you’ll think more clearly about each aspect of the feature, you’ll avoid unnecessary bloat, and you’ll be more creative when challenged to achieve those goals. Here’s an example of goals for a Tomb Level-Scripting feature for The Sims 3 World Adventures:


Goals

  1. Tomb Object Modularity. Traps, puzzles, doors, and rewards should interconnect with each other such that we can create countless combinations of interesting and challenging spaces.

  2. Non-Linearity. Allow entry to many tombs without being on an official adventure so players can stumble upon gameplay while exploring the world.

  3. Recognize and track progress. Surface the player’s progress through tombs and adventures in order to offer more goals and achievement-based motivation.

These goals are short, sweet, and they drilled to the core of what we felt was important for our tomb development system. Goals like this will set you up to craft a better design.


2. Use Strong Statements. Ditch all Mitigated Speech.


New designers tend to write design docs like they’re compiling a Christmas list to a stodgy Santa Claus.


Weak:

  • It would be great if we could get a seamless world with a huge playable area.”

  • “We might want to let players use the character creator to make NPCs for the town.”

  • “If possible, it would be cool to kick fallen enemies and have a chance of coins spilling out.”

Every time developers read lines like this in a design doc, they lose confidence in the designer, and usually file these parts of the design into their “we don’t have to do this” category.

Designers need to take a stand in their designs. Brainstorms and early design meetings are for discussing possibilities and uncertainties, but design documents are for telling the team exactly what the game will be. Even if the designer doesn’t entirely believe in what they're writing.

All designers are filled with doubt about some of their designs. Will a HUD-less screen work? Will the engineers laugh at me because I want to pull 20,000 cooking recipes from an online database? Will animators refuse to animate a snake latching onto a character’s face and flailing about? Yes. They will! This is normal, and this is necessary. It’s part of the process, and it leads to great conversations that narrow in on what’s right and possible for your game.

So take a stand. Ditch all mitigating speech from your designs – no more maybe, possibly, could we, it would be cool if, etc. (Malcolm Gladwell writes, in Outliers, how mitigating language likely led to at least one plane crash when a cockpit engineer and first officer were too soft-spoken to the higher authority of the pilot, rather than speaking clearly in a dangerous situation.) In addition, be as specific as possible. Instead of “large,” say “25 square kilometers.” Here’s a rewrite of the design statements with strong and precise language.


Strong:

  • “The world will be a seamless, 25 square kilometer playable space.”

  • “Players will be able to use the character creator to make NPCs for the town.”

  • “Players can kick fallen enemies to have a 20% chance of additional coins spilling out with value equal to 150% of the gold found in the enemy’s normal loot.”

Much better. This was one of my first and most important lessons as a designer, thanks to my boss and Creative Director at the time (Matt Brown, of Maxis, Blizzard, Roblox).


3. Lots of Bulleted Lists!


Design documents are, effectively, lists of tasks. So why not present them that way? Damion Schubert says in his fantastic GDC 2007 presentation, How to Write Great Design Documents (a must-read for all designers), “Programmers almost always want a short bullet list (they kind of like checking things off lists).”

This is a bird’s-eye view of the entire design for The Sims 3 World Adventures tomb technology which allowed designers to script tombs by interlinking object behaviors of traps, triggers, and objects. Notice that the majority of the text appears after bullets:



A bird's eye view of The Sims 3 World Adventures "Tomb Technology" design doc.

And here’s a snippet pasted from the doc:

Each bullet is either a specific implementable task, or a header for a subset of specific implementable tasks. Write your designs like this, and they will be more readable and more actionable. And your engineers won’t hate you as much. (They may even begin to like you.)

Non-bulleted text is usually an overview, introductory text,  or otherwise non-implementable. Another benefit of bullets is that they naturally reduce vague language. It’s easy to hide uncertain statements within large blocks of text and not even know you’re doing it. But bullet points shift your mind into making strong, concrete statements.


4. Color Code for Disciplines and/or Readability


You may have noticed that I use plenty of color in my design docs. This was inspired by the great readability of gear hovertips in World of Warcraft (which had improved on a similar presentation in Diablo II). Take a look:



Even if you were illiterate, the coloring conventions would tell you that the Infernal Mittens were more rare (purple vs. blue), you could not equip either item (red text), that the Mittens had some unrealized bonuses (gray text), and that both items had additional bonuses (green) on top of normal stats. Now, translate this to design docs. I use color for three things:

  1. To draw attention to specific disciplines (art vs. animation vs. UI, etc).

  2. To emphasize hierarchy (section headers & sub-headers).

  3. To emphasize importance.

Here’s a fictitious example for an interaction between a Sim and a Piñata:

Key: Green = Interaction Orange = Animation Purple = Important Object or Related Design (like Traits) Pink = UI Requirement Red = Visual Effects Light Blue = Standalone Audio (not attached to animation)


You should adapt your color styles to the needs of your game and your team. Perhaps you need to call out a lot of text requirements, or your world builders will want to easily find aspects related to level design. This may seem like a lot of effort, but it’s worth it. Suddenly, your key disciplines will find it much easier to absorb your designs and find the portions relevant to them. Want to know all the UI requirements in a 15-page design? Just look for the pink sections. I’ve had people move onto different teams, then tell me they miss this formatting and cannot do their jobs as easily. The success emphasis in my design docs has spilled over into my style in these posts. I use bold to emphasize important points and to create visual anchors, which also helps prevent readers from skipping blocks of text. I highly recommend reading Lazy Eyes (How we read online) by Michael Agger – an article that also deeply influenced my formatting style online and in design docs.

5. Use Images to Set Mood or Explain


This one is pretty simple: a picture is worth 1000 words in a design doc. I like to use a picture at the top of every design document to set the mood and draw the reader in (and I do the same thing with almost all of the articles on my website). For example:

Place a mood-setting image at the top of each design document.

And if a design point is vague with words alone, consider supplementing with an image:

An example from The Sims 3's design doc for Painting Skill.

In fact, if you have a complex design with many interwoven parts, a design document dominated by imagery can be preferable. For more about this, check out Stone Librande’s great One Page Designs presentation from GDC 2010:



Summary


A lot goes into writing and formatting a great design document. This list is the best of what I’ve learned, but there are plenty of finer details. I highly recommend you follow the links to Damion Schubert’s presentation, Stone Librande’s presentation, and the Slate article Lazy Eyes (How we read online) for more advice and inspiration.