Removing The 'Tech' From 'Design Document'
by Michael Sikora

Who are You?

If you're a programmer who has written at least one software title, and you have never written a technical document, this is your ticket to creating games faster. Yes, I said faster. And after all, aren't good game programmers all about speed?

This Isn't For My Benefit

Let's get some things straight, I've never worked on a blockbuster game title, so we're equal in experience there... well, maybe not. But I have worked commercially on a game before, and I know the pressures caused by having to meet deadlines (I'm positive I know why they call them deadlines now), getting paid, and adding features that were never mentioned six months ago.

I didn't write a technical document.

If I had, I know I would have completed the game in half the time. Oh, and like all good little programmers I created a design document with my employer (designer/creator). I even mentioned that we could use DirectDraw, but that was the extent of the technical design. (As a side note, take a look at how many game design articles are available online, including here at GameDev.net. Why aren't there any technical design articles?)

If you've never thought about using a technical document before, and if I haven't lost you yet, it's time to explain the title of this article. As you probably already know, design documents are essential to any game. You need to know what the game is about, what it will eventually be, and the design document exists for that purpose. On the other hand, do you really need to plan out how to implement the graphics library in advance? You already know Mario is going to have a red hat. You can figure out how that red really isn't Luigi's hat when you get there, right?

Sure.

In fact, many game programmers do exactly that every day. Heck, you should see some of the MMORPG design documents that are out there. They are huge! But if you go to the creators and ask them for a technical document, they might look at you like you're speaking another language. Or (*cringe*) they might say that the technical document is included in the design document. Funny, there are only a few MMORPG's in working order. I wonder what happened to that 300 page design document Zeophytie posted last year…

'Tech' From 'Design Document', Huh?

Up until this point, I really haven't discussed why you need to have a technical document. (If you don't know what a technical document is, or even if you do, don't worry, I'll explain that in a moment.) I think I've made it clear that you can make a game without one, but that's bad practice if this article is trying to encourage you to write one, eh? What did happen to Zeophytie's MMORPG anyways?

I'll tell you what happened.

Zeophytie, being a veteran C/C++/ASM/VB/DirectX/OpenGL/MFC/Winsock programmer, knew how to write every functional piece of code he would need. And buttons to bottles, he did just that. Unfortunately, when he got done at 3am (all projects end at 3am, don't ask why ;-) he had a sudden realization: "How is any of this going to work together?" Even worse, he had just received the source files from his 4 other programming buddies 2 days before, and he realized that after reading them over, the text all looked like it was written in another language altogether.

I'm not sure I need to finish this story, because, well, there isn't much to tell. Zeophytie asked all the other programmers to modify their code (meaning a rewrite) while Zeophytie tried to make his own code work together. Needless to say, the team fell apart, and people went their separate ways. End of story.

360 Degrees The Other Way

I didn't write all of the preceding because I like to ramble. (Ignore any proof that may exist in the GameDev forms; it's an imposter poster, I assure you.) I wrote it because, even if you read this entire article, it's not going to make a difference unless you use the things you learn. So what's the solution?

YOU CAN DO IT

How?

Open up a text editor. Heck open up your compiler if that makes you happy. Now look at the blankness. That's not a technical document.

This little exercise wasn't a good laugh at your expense. Rather, sometimes it's good to clarify what something isn't before trying to explain what something is.

Here's the definition of a technical document from GameDev.net's Game Dictionary:

"A specification for all of the programming algorithms, data, and the interfaces between the data and the algorithms."

Okay, while that's a great definition, it teaches you nothing. Here's what you NEED to know:

A Technical Document IS:

A place to write the requirements.
A place to write an overview of how objects/functions/data interact.
A place to specify coding conventions such as variable naming and commenting.
A place to list all the technologies the game uses, and how the game benefits from them.
A place to list all the classes/structures/variables, and what they are to contain.
A place to list all the functions/routines and what they are to do.
A place to list in what order modules will be written.
A place to list file types, data layout, etc.
A place to give considerations to future additions, and "what if"s.
A place to list projected system requirements and dependencies.

A Technical Document IS NOT:

A place to write the game's story.
A place for source file comments, or worse, code. (Excluding example snippets/PDL)
A place for describing how levels are played through.
A place to develop characters.
A place to plan marketing, or distributing.
A place to think about how to get the game published, or attract investors.
A place to discuss *mood*, *setting*, or any emotional quality.
Most of all, a technical document is not a personal diary! You don't write about what your girlfriend said about those ugly blue shorts of yours! Gee-e-e-ezzz. (You'd think they'd get over taking you out in public by now…)

Now that we've cleared up what a technical document is, and what it's not, I think it's time we had an example, eh?

Pong? No. 3D Shooter? No. Tic Tac Toe? You must be kidding…

Unfortunately I'm not. Although in the less fanatical sense a a technical document for program as small as a tic tac toe game may be overkill, it's an easy example to work with. More importantly, I'm going to give you a major heads up.

Technical documents not only don't need to look like each other, they probably shouldn't.

Considering the vast variety in games and the technology they use, I'm not going to have you memorize some arcane template for a technical document. Although you might benefit from from something like that, this isn't university, you're going to take what you learn here and apply it to the real world.

Okay, the following example doesn't try to fill in all the details (yes, even for a tic tac toe game), but it gives an idea of how you can take apart the concept and use it for your own work.

The "Note"s aren't part of the document, they just comment about the document.

TIC TAC TOE

Technical Document

Requirements:

The program must be able to run on any Win9x/Me/2000/XP system.
The program must not require any additional files/dependencies, and it needs to be small.
It needs to run on any computer with a Pentium class CPU, and as little as 16 megabytes of memory.
It should be controlled exclusively by the mouse. No other input device should be required.
The game is for two human players.

Note: Simple eh? Your projects will require more then a point form outline, but that doesn't mean you can't KISS. (KISS - Keep It Simple Stupid.)

Overview Of Design:

The game will be written using a C++/WIN32 solution. It's will consist of a few small classes which define the entire game. The windows code will be in straight structured style, while the game module will be forged object orientated style. We considered using DirectX, but not all systems have the capacity or drivers, so the standard windows gdi drawing functions are the choice.

Drawing:
The game will use the standard shape drawing functions of windows. There is no art, everything is to be drawn as geometric shapes. The game board will be drawn as lines, and the X's will be lines, and finally O's will be circles. (No, that wasn't obvious =)
Note: Information on colours and font types should be in the design document! You might cross reference what these are by referring to the design document, so you know what you need to support, but not here.
Input:
The mouse will be used for input. The menu and item in the client area of the window can be dragged, clicked, and double clicked.
The mouse will be used for both human players.
No mouse operations need more then two buttons.
Note: Cursor colours/art should be in the design document!
Logic:
The game data is essentially kept in a array that holds the marking pieces of the game.
Note: There is more you could add here, but I'm sure you get the idea by now ;-)

Project Break Down:

The project has a total of four files. Two header files, and two source files. One set will contain all game related code, and the other will contain all window specific code ( although the drawing and sound code will be encapsulated to some degree in the game code.)

Game Module:

Class TicTacToe
Properties:
Current players turn
Board array
(etc…)
Methods:
Initialize - Clears variables, sets game states all to beginning values.
GetInput - is called and passed mouse position and button states. Uses this information to check to see if user has placed a game pieces (X or 0)
Draw - is passed a window DC and draws board in client area.
(etc…)

Window Module:

(Same format as above…)

Note: Usually, each function would have a description of everything it does, but I'm assured as an experienced programmer you can do that yourself ;-()

Future Considerations:

In the future, the game might need the addition of an AI component. The class's ability to handle it's own input will allow us the addition of an AI component quite easily with out changing much of the existing code. (Note: Not there was much to begin with, but don't be too cynical =)

Conclusion… Is It Really Over Mommy?

Stop looking for more, there isn't any! Really though, if you thought this article was about forcing you into some narrow-minded view of how you should plan your games out, that wasn't my intent. I'm just (like any good Samaritan *wink, wink*) passing on some experience. My goal was to somewhat stimulate your thoughts in how you plan the technical aspects of your game projects. It doesn't really matter how you deal with technical planning...

AS LONG AS YOU DEAL WITH IT! (AND PROPERLY ;-)

Anywise, I've given enough trade secrets for one day.

Michael Sikora, at guardian-light@cogeco.ca.

Discuss this article in the forums

Date this article was posted to GameDev.net: 2/20/2002
(Note that this date does not necessarily correspond to the date the article was written)

See Also:
Code Design
Featured Articles