Writing Better Game Design Docs

22 Mar
22 March 2011

Text has an important role in game development.  From pitches to system designs to team emails, effective writing is a valuable tool.  Which is why it’s always surprising to see how awful most documents are or how rare it is to encounter anyone interested in changing this.

I’m certain myriad people have been tasked to improve internal docs at various companies.  As far as I can tell, that results in templates, naming conventions, filing schema, preferred fonts, and similar standardization details.  In other words: nothing that will produce more effective writing.

I’ve been scribbling game-related things of one variety or another for more than thirty years.  As a packrat, I have a fair amount of that piled about, ranging from six-year-old me’s awesome Atari 2600 pitches to my first professional work on Age of Empires.  Looking over it, I assure you that I’ve made a vast number of mistakes and inflicted my share of the crappy docs on people.  But my work has  improved over the years and I spend a lot of time thinking about how to write things that are more useful to the team.  These are some of the big changes I notice across years of docs.

It’s great to be short and ugly.

My early docs show that I, like a lot of novices, labored under the delusion that mass and presentation signal productivity and quality.  My early game designs resemble phonebooks.  I emulated the formatting and layout I saw in published material.  (In some cases, thanks to a highschool buddy whose father owned a print shop, I did more than just emulate.)

Today, these same factors form the foundation of my at-a-glance opinion on almost any document.  If a 300 page spec that looks like it should be in hardcover at a Barnes & Noble lands on my desk, my first thought is, “Amateur.”

It’s easy to understand the origins of this approach.  It’s natural to want to make your work look professional and to demonstrate your effort through quantity.  What makes it persist is a little more insidious.

In design, you’ll often have a task to write a spec for a system.  You’ll spend a week or two looking at all the pieces, thinking about how they fit, talking to people, trading emails, looking at other games, having meetings, whiteboarding, and so on.  Then you’ll sit down to hammer out the spec and it’ll fit on two pages.

You’ll think: Two pages?  I’ve been working on this for two weeks.  It can’t be two pages.  This looks like an hour of work.

Let that go and twelve hours later you’ll be scouring Google for illustrations to add to your 20 page document and cycling through a dozen different fonts.

Today I pray at the altar of utility.  A good design document is one that communicates the necessary information.  The easier it is for a reader to get that information, the better the document.  The easier it is for a writer to prepare that document, the better the document.  If I can convert weeks of meetings, thought, and discussion into two pages of spec, I consider it a massive success.

“Nobody is going to read this.”

While it may not be true, it is often worth writing as if it is.

My early design documents show the same hand I use when I sit down to write fiction.  Within are signs that I had worried about things like cadence, sentence structure, and word choice.  When I revised these, it was often to refine language, adjust a turn of phrase, or amplify some portion of the content.  In most cases, a revision pass yielded a longer document.

Today, I do my best to shift gears away from the fiction mindset.  I spend as little time as possible worrying over things like cadence.  If I’m concerned about word choice, it’s because I notice a word I think someone might not know and want to replace it with something more common.  When I revise, it’s often expressly to take a hatchet to what I’ve written, to go in and look for any place where I can simplify, delete, or reduce.

Thinking “nobody is going to read this” is a way to keep the shortest path at the top of your list.  What’s the bare minimum required to achieve the aims of the document?

The audience is the team. 

My early design documents read like I expected an alien civilization to find them buried in the rubble of a long-extinct humanity and try to use them to make a game.

“Hitpoints are an abstraction of the health of units, used to quantify the damage they can absorb before death.”

Wow.  Next up, an explanation of “mouselook.”

Most design and internal pitch documents should be aimed at the people you work with every day.  You (hopefully) have shared experiences and understanding with these people.  You shouldn’t need to explain hitpoints to anyone working at a game development studio.

The bulk of my doc work today assumes both that the reader knows what I know and also that I’m not leaving for a year of vacation on the moon as soon as I send it around to the team.

Documents can be edited.

I started writing before the era of the word processor.  I couldn’t deal with errors.  Pen and paper have no undo, so a slip or misspelling meant re-writing the page.  Which I did.  Frequently.  This horrible flavor of OCD carried over to my early design work.  I can see it acutely in ancient concept pitches bloated to two or three times the pagecount needed and filled with unnecessary low-level detail.

The compulsion there is to get it right.  The idea would be clear in my head and I’d think of a dozen ways to illustrate dimensions of it to every possible audience.  I’d want to include all of these in the pitch, for fear of not reaching a particular reader.

Attempting this, trying to achieve design work that perfectly explains concepts to a universal audience all by itself, is spectacularly counterproductive.  It takes far more time to produce, it’s harder for everyone to read, and even done masterfully there’s approximately a 100% chance that someone will form an image in their head that varies from the one you’re intending to plant.

Today, I try not to worry about safeguarding against all misperceptions.  I don’t sit on design docs they are “error-free” and deliver precisely what I want to communicate from every angle.  Instead, I do my best to ship early drafts to the team and I try to set expectations that include some degree of error and confusion.  Errors in documents can be easily corrected.  Confusion can be addressed, often by simply talking to someone (a far better use of a designer’s time compared to attempting to preemptively doing the same for all audiences in text).

As an added bonus, I find this approach has a number of other advantages.  For example, because you spend vastly less time working your design out to the Nth degree, you’re less invested in the specifics and more willing to give alternative ideas consideration.  Also, because their first encounter with the work is when it’s 20% done instead of 90% done, you make better use of your team’s expertise and foster a more collaborative environment.

Write when it is needed. 

In most cases, a design spec written more than a month in advance of implementation can be replaced by a Chinese takeout menu with no appreciable loss of utility.

Early in my career, I attempted to have the design “done” at the start of a project.  On Day One, I wanted to be ready to go with a complete spec.  This was obviously before I understood the role of playtesting and iteration.  Having experienced that, and having been through a number of development cycles, I now know that a complete Day One design is both impossible and counterproductive.

In my more recent work, I try to concentrate on identifying the high-level pieces we’ll need to think about and what those imply to our tasklist and schedule.  I keep notes on these, details to keep in mind when the time for a spec comes.  For the actual writing portion of things, I shoot for “just in time design” – when the need begins to surface, the relevant parties get together and rough out a basic outline for the design dictated by the current state of the project.

If it’s stupid but it works, it isn’t stupid.   

Browsing through my collection, I notice plenty of design docs that violate most if not all of these “lessons learned.”  Some of these were nonetheless very successful.  The reason for that is that the goals aren’t always the same.  Sometimes, you’re not shooting for brevity in a draft doc aimed at the team.  Sometimes you’re writing a pitch to get a publisher interested in a project or an intro for your first round of beta testers — people who might value lengthy, polished, slick-looking, all-bases-covered docs differently than you and your team.

In those cases, I happily ignored all the things I feel produce the best actual results and instead did my best to deliver in the format most likely accomplish the goal.

Rules are great, so long as you know when to break them.

Tags: , ,
0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply