Opinion: How I Document A Game

[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. Conclusion Time to unceremoniously dump links on you!

• Table of Contents – a jump off page that links to almost everything
• Concept Document – the major overview of the entire project
• Thrall – an example of how I go about describing and documenting a character. Has three parts:
  • Description
  • Animations – Note: if you change the url to .xls, it will download the excel file.
  • Features

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.]