Gamasutra: The Art & Business of Making Gamesspacer
View All     RSS
October 21, 2014
arrowPress Releases
October 21, 2014
PR Newswire
View All

If you enjoy reading this site, you might also want to check out these UBM Tech sites:

Opinion: How I Document A Game
Opinion: How I Document A Game
August 8, 2011 | By Mike Birkhead

August 8, 2011 | By Mike Birkhead
More: Console/PC, Business/Marketing

[In this reprinted #altdevblogaday-opinion piece, NetherRealm Studios' Mike Birkhead outlines how he lays out a "Concept Design Document" the best way he knows how: by creating a game from scratch to explain the process.]

I have worked on five games in the past six years. I have written countless word documents, set up countless excel files, modeled levels, written code, and even drawn a few maps; but I cannot show you any of this.

This has been bothering me for a long time. Of all the things I set out to do when I started writing, my first and greatest goal was to get down and dirty. I was going to "keep it real". Much as I love talking about abstract concepts like fun, play, and other great game design concepts, I felt there were not enough people really showing what the system designers life is like. The REAL work. You know, documentation.

I have always been a stickler for documentation. And not just documentation, but efficient documentation. I enjoy it, and I like doing it better and better each time. I look down on designers that can't organize their files cleanly, that can't set up a list in Excel.

In short, I'm that guy. But dammit, it's important! The larger the team gets, the more important it becomes to be efficiently organized, and I often wonder how others do it. My style is built up from the great ideas of the designers I have worked with, which I'm sure was built upon the great ideas from designers they worked with.

Lately there have been a lot of great posts on AltDevBlog talking to designers in school, or people first starting out, and it got me thinking. I wanted to share my style with others, so that they too can grow; and then hopefully others would talk about how they do things so that I can improve. But how? In exasperation I thought, "Well, gee. I'd have to design a whole game from scratch in order to talk about it."

So that's what I did.

Game: the Verbing Noun

For the past three weeks, I have spent my free time writing documentation for a fake game. I am now going to post the entire thing online. Some might call me crazy. Maybe I am.

So what is Game: the Verbing Noun?
{Game: the Verbing Noun} is a single player action adventure game set in {FamousSetting}. The game takes the visceral action of games such as {Some Action Game}, mixes it with style switching from games such as {Some Other Action Game}, and finishes it with {buzzword} from modern games such as {Popular Franchise}. All of this is mixed with both world class art and tech to create a game that is as brutal as it is beautiful.
Now, I could follow this with a link to the docs, and just unceremoniously dump you into the deep end, which is fairly tempting, but I would be remiss. I shall start by explaining some of the basics of what is there, and then, at the end, dump links all over your face (and maybe a surprise).

First let me state that this is not comprehensive, not in the slightest. I have written as much as my little wrists could handle, but there was only so much I could do. Of what made it, there are three major topics to cover: the concept document, the table of contents, and the many views of the Thrall.

Conceptual Design Document

Most people call this the "Game Design Document" or, more informally, the GDD. I call it the Concept Design Document, because mine are less all encompassing. It lays out the entire game in broad strokes. If you read the CDD from cover to cover, you should have a firm grasp of the concept (get it) of the game.

I follow the philosophy that the more specific the document, the more specific the information contained with it. I write this first, and it is hard. It gets rewritten like a million times. When I first started out, the game was basically about Conan, set in Hyboria, and the combat involved lots of weapons. When I went to create enemies, however, the ideas I had didn't fit with that style of game, so I went back and things changed. Repeat.

Once you have finished reading CDD you will have a broad grasp of four major categories: player, setting, cast, and world. What can the player do, where does it all take place, who does he meet, how can he get there, and what happens when he does. But what happens when we want more detailed information?

Table of Contents

The first trick to my style is that the table of contents (and even the folder structure it is all contained within) matches the major headings for the CDD. If you have read the CDD, then you have learned how everything for the entire game is going to be organized. I did my best, despite many missing docs, to show how it would look once more documentation was written.

But what does it look like when you click on the Thrall?

Many Views Of The Thrall

The more specific the document, the more I begin to tailor it specifically to its intended audience. In the case of something that the player is going to be fighting, the Thrall, there are several views of the same guy. He has his description, a list of his animations, his required features, and stuff for effects and sounds; sometimes, I even do power point slides as a story board. Point being, when an animator is looking up needed animations, he doesn't need to know that the Thrall can only be thrown when he gets to 20 percent health, but what he does need to know is that the Thrall's idle stance is to be hunched over. The right info for the right audience.

This same process is done for other things, such as the Lever, when necessary. But other features, such as the document dealing with Spawning, do not require such fine tuned depth. Again, it's about trying to understand your audience.

Wait, Why Is Everything HTML

Despite the obvious fact that I'm trying to showcase all of this on the web, I had other reasons for doing everything in HTML. My style of documentation, which is to say lots of small files, lends itself very well to dynamic HTML. Though this particular instance is not dynamic, it could be; and allowing for a dynamic quality makes things like "change the Thrall's health" not the complete nightmare it normally would be.

What about Excel files, and hey, while we're on it, where are your Excel files? First, you might have noticed, on some pages, there was a little bit of text that said, "(Excel)". If you click on that, it will actually download an excel file for the information on the page. (See, not forgotten, and in fact very much a part of my docs.) But what happens when you try and go all DHTML? Well, in that case, I would probably do the work to drop Excel completely. I firmly believe that web is the way!

So, that was one reason, and the other was formatting. How you display your information is just as important as the information itself. I constantly fret that Heading 1 isn't clean enough, and that you can't tell the difference between Heading 2 and Heading 3. Yeah – totally that guy. By doing this all in HTML, and by using CSS, I can make every file look exactly how I want, and guarantee it is the same for all of them.


Time to unceremoniously dump links on you!
The game may be fake, but the documentation is real. This is a reasonable facsimile of how I approach the task of designing a game's many layers of documentation. From the large to the small; from the general to the specific; from the programmers to the animators; from the Word documents to the Excel files.

Once I have given my wrists a rest, I plan to go back and keep adding. I still need to add an example of how to balance the economy, and I haven't even touched on level design at all.

This is the form and structure of how I do things, but it does not and should not necessarily be how you do things. Every game is different, and every genre of game is different. My hope is that this structure and some of its ideas, maybe a lot the ideas, will be enlightening; but I also hope that some of it will not and, in fact, you will look at it and say that it can be done better; that you have seen it done better. I hope that you will join the conversation and share how it was done better. In this way, and only in this way, will the game designers of the world truly grow.

Speaking of sharing and growing – I told you I had a nice little surprise at the end – this entire process (how I set this up) was done and stored on GitHub. And here it is if you would like to download it as a zip.

The major benefit of the GitHub package is that it includes the "helpers" folder, which contains templates for all the documents I write. It makes my life easier, and I assume it will make your lives easier too. So, please, feel free to use it. Or fork it and make it better.

But most of all, enjoy.

[This piece was reprinted from #AltDevBlogADay, a shared blog initiative started by @mike_acton devoted to giving game developers of all disciplines a place to motivate each other to write regularly about their personal game development passions.]

Related Jobs

Treyarch / Activision
Treyarch / Activision — Santa Monica, California, United States

Senior UI Artist (temporary) Treyarch
Treyarch / Activision
Treyarch / Activision — Santa Monica, California, United States

Lead UI Artist
Vicarious Visions / Activision
Vicarious Visions / Activision — Albany, New York, United States

Art Director - Vicarious Visions
Infinity Ward / Activision
Infinity Ward / Activision — Woodland Hills, California, United States

Senior AI Engineer - Infinity Ward


Anna Tito
profile image
I am always interested too see new ways for documenting designs, thanks for this! Now off to refine my current documentation :D

Sebastian Bularca
profile image
I was just talking about this fact with my wife this morning, with emphasis on the fact that most of the game design books out there are still talking 25% of design and the rest about ideology, marketing and production. They do not contain actual detailed design examples. Luckily she found you today, and I felt not so alone anymore, hehe... We have pretty much the same problem, although, I personally have more like 1/17 of your experience. Our conclusion was the same - We have do design our game from scratch in order to share its documentation. I hope more designers will take note of your initiative.

Laura Bularca
profile image
Mike, thank you for this very well detailed article. I was just talking to my husband this morning (he is a game designer) about the various game design books available and how they never share something concrete and real, because those documents belong to the company you work for and therefore cannot be shared. Even the GDDs out there that have been shared lack a lot of stuff. And so the conclusion we reached was exactly like yours: this information needs to be shared, and to do so, the only good way to share it is to invent a game and document it. Who knows, maybe there is a team out there who actually likes the idea and can build the game, if the docs are good. Yours are convincing! How would you feel to see Thrall done?

If you add to your documentation, please keep us all posted. Also, I would be very interested to see what debates your article spawns, so update us about the feedback you get, in case you don't get it here as a comment. Thank you - I respect and admire you for the work you did just so you can share this!

John Murphy
profile image
This is good. It's really easy for a design doc to sprawl in a disorganized way. I'd really like to see the beginnings of a level design example.

Aurelio Provedo
profile image
Nice article. Hope more game designers join us in sharing their workflow.

What do you think about using MediaWiki? It's amazingly easy to edit; highly readable; everyone is used to Wikipedia; almost anything can be embedded; revision histories that you can rollback; discussions; organized folder-like structure that is very easy to understand... To me, it seems obvious that a MediaWiki GDD is a better option.

Richard Rabil
profile image
Hey Mike,

I’m way late in commenting, but thanks for writing this article! I’m a full-time technical writer, and I’ve often wondered how game designers approach their documentation. You’re right (in my opinion) to get picky about things like outlines, consistent headings, spacing, structure, formatting, and terminology. These are the types of things that can dramatically reduce comprehension of complex information. Indeed, if you can save even a few seconds of time for each person, the cumulative effect can be massive – especially in projects with large teams.

You said, “I firmly believe that web is the way!” I couldn’t agree more. Thus Aurelio brings up a good point about MediaWiki. I haven’t worked with MediaWiki before, but I have worked with Confluence ( It’s an excellent tool for online collaborative documentation, and could be a great mechanism for implementing the structure you’ve designed.

A big advantage of Confluence (and MediaWiki, too) is that you can better reuse content and maintain dynamic information. The reality is, names of monsters will change, statistics will be updated, and you’ll want to reuse chunks of content here and there. With something like Confluence or MediaWiki, you can create libraries of reusable text, so that you can edit it in one place and see it update everywhere else. Also, you can define variables for your content, so that if a piece of information changes in one place (say, a monster’s name), it will cascade to other instances. I would imagine that would be a nice capability in fast-paced game development environments.

I wonder what the ratio is of studios that use more advanced documentation tools (e.g., wikis with advanced capabilities to handle dynamic information) and those just using Word? Hmmm.