Design/Concept/Requirements docs, cont. from MMOG discussion

[Jayce]

Don't forget concept documents. Concepts generate requirements generate design, if I remember the terms right. Games need concept documents and requirements documents (to highlight dependencies and such), but I can see them doing rapid prototyping that becomes a template for the design document.

...so that's now three times the "required documents" for a game?

That's kind of my entire point :)

Nah -- it's like ISO certs. If you're going to do it at all, you pick the type that fits your design needs. My shop now? We have concept documents -- a few pages spelling out the major points of the product and tying those to what the customer was asking for -- it functions mostly as a checklist to make sure what we create does what the customer wants. For our most complex product -- which interfaces with other people's stuff and has some rather rigid QA requirements -- we have a pretty large design document that spells out the interfaces (it's updated as the product evolves) and dependencies. It's mostly used when changing core mechanisms, to make sure we don't break other people who use it.

Those are purely internal, and they're not that much more intensive than simply documenting your code. I'd think MMORPGs -- with the interlocking mechanisms and constant change even after delivery -- would absolutely require documentation like that. As a minimum. If you don't have that, how do you prevent constant fuckups where supposedly simple change X fucks up mechanism Y that was using X, but no one told the Y people you were fucking with X?

I think there is a definite difference between sub 10 person shops... maybe even sub 50 person... and higher.  With < 50 or so, which probably means 20 full-time devs (the maximum social circle number, I read somewhere) everyone is pretty much on the same page just by social interaction.

Beyond that, you start having X, Y and Z problems as above.  As your shop grows above the magic number, people start getting mad because what worked a month ago ("Just tell Bob, he's the keeper of that system") can become a political war because no one understands what's happening.  And of course they blame the new guys, who blame the old guys for keeping everything such a secret.

[Morat20]

I think there is a definite difference between sub 10 person shops... maybe even sub 50 person... and higher.  With < 50 or so, which probably means 20 full-time devs (the maximum social circle number, I read somewhere) everyone is pretty much on the same page just by social interaction.

Beyond that, you start having X, Y and Z problems as above.  As your shop grows above the magic number, people start getting mad because what worked a month ago ("Just tell Bob, he's the keeper of that system") can become a political war because no one understands what's happening.  And of course they blame the new guys, who blame the old guys for keeping everything such a secret.

On the one hand -- I agree. I work in a small shop, and most of us bitch about documentation because it really is easier to walk ten feet and say "Hey, Bob -- come look at this and tell me why it's not working -- I'm calling your code here, and this is utterly wrong". Bob'll come straighten you out (or say "Oh shit" and go fix his code. One way or the other).

But we have a really sticky Dev team -- we haven't had a Developer leave in something like 3+ years. I get the impression a lot of game devs are like this -- for single player games, console games, and regularly multi-play type of games. You sign on, you see it out the door, your tech writers write it up, and then some barely past intern-level schmuck gets to play bug-fixer for it for a few years as he learns the ropes. That's fine -- if you document the code, and the support staff is just there for bug fixes.

MMORPGS are different beasts. They're not ever finished -- or even mostly finished. Which means even if the MMORPG shop is fairly small, churn is going to be a huge problem. You might be digging into an interface no one has touched since Bob -- who left two years ago -- wrote it. It might be a mechanic that's utterly undocumented, and no one left has more than a vague idea of how it was originally designed.

Lack of documentation means Devs have to sit down and work out what the hell a mechanic is really doing, try to decide if that's what it's SUPPOSED to be doing, and then try to puzzle out what might happen if they change it.

Small shops might as well be big shops if the churn is high enough, and product development goes on long enough. Look at the clusterfuck of SWG -- so many Dev teams in and out of the damn game, so many damn changes in so quick a time -- you could tell just from their publishes (or whatever they're calling it) that they kept breaking crap by mistake, because no one understood how huge chunks of the game worked anymore, and no one had time to figure it out.

I still think the best way of handling that sort of challenge is to start with a simple concept document -- outlining goals, core mechanisms, and gamplay in simple english. You start putting Dev teams on that, let them start prototyping and working out how the mechanisms should interact. Once you've got the skeleton in place, you need to get back together and document it more thoroughly -- map out the interfaces, the way the mechanisms are supposed to work. Give that back to the Devs and let them fully implement in.

It's kind of a back and forth -- you take generalities and the bare minimums for interfacing, and let your Developers play with it. You get feedback and results, and incorporate that. If you keep up with it, by the time you hit  alpha you should have fairly detailed documentation on how the game works. What affects what and where and how. The game was still created organically -- you start with a good idea and keep playing with it -- but you have good documentation. As long as you keep up with it through alpha and beta (when changes come quick and fast), by the time you launch you should have a rigorous enough document that Jow Newbie -- hired on to replace a Dev moving to another MMORPG -- can read it and find out what's going on with a given area of the game, even if the original designers for that segment aren't around anymore.

[Stephen Zepp]

Just to further the "prototype instead of design doc" concept:

Why describe in plain english a game concept, when you can prototype it rapidly and demonstrate it instead?

The concept I was implying when I was talking about game design documents going the way of the dinosaurs is that the logical end of the concept of ever-more complex design documentation is a playable demo/prototype that not only can be used to "describe" a game concept (as a design doc does), but can also prove or disprove the concept in (depending on your toolset) almost the same amount of time required to just describe it.

GG, and many other studios, have moved completely away from "design/concept docs" because in the time it takes to write up a doc (with gui mockup images, use/play cases, and related product that makes a design/concept doc at least somewhat useful), you can sit alone, or with a buddy, and actually make the game and see if it is actually fun.

Specifics are still under NDA, but our next release of Torque Game Builder allows you to tie together dozens of game play elements with literally minutes worth of effort and actually play a game, instead of spending hours producing a document that then has to be explained in a meeting, mocked up with artwork to demonstrate interfaces and use cases, and all other sorts of non-productive effort.

And that's just our version--many studios are using rapid prototyping tools to actually produce playable "game concept descriptions", instead of simply writing about them.

[Margalis]

I agree with Stephen. I think some sort of documentation is important but probably not more than a few pages, and those need to be focused on the general concept. For example for the GG game "Think Tanks:"

"Players choose from a few different types of tanks and battle out, driving and shooting at each other and gaining wacky power ups."

I just designed Think Tanks.

[Morat20]

I see what you mean. Heck, we do enough "proof of concept" stuff around here that's entirely built around lunch-time spitballing. We mock something up, show it to customers, and get a yes or a no and go from there.

Basic concepts don't have to be written down -- but I don't see a real difference between writing a few pages of descriptive English and a demo prototype -- a prototype is nicer and easier to demonstrate, but the practical difference (to your coders) is virtually nil. All you need is a rough roadmap. Still -- you talk about a document with gui mockups and use/play cases -- that's far more detailed than what I was trying to convey. I'm talking something like (if we use WoW) "DIKU-style MMORPG utilizing Warcraft setting. Factional PvP, endgame raiding, focus on questing XP means for advancement over grinding. Secondary crafting as "useful" but not required" -- then maybe a list of potential features, sorted by 'coolness' value or criticality."

I think some games (esp. resource management games like Railroad Tycoon and 4x games) require considerably more up-front design thought, but I think that's dictated more by the type of game you're making -- some games need a hell of a lot less.

But my main concern isn't with original development -- it's the post-developmental phase that's common with MMORPGs. It starts with alpha, reaches a fever pitch in Beta as large-scale testing starts showing you the problem areas, but it never really goes away. Each patch, publish, or expansion tends to change at least SOME core mechanics and adds complexity. That leads to bloat -- code and feature -- and gameplay drift.

The more interdependent your game is (SWG as a good example) the more difficult it is to make a change that doesn't affect obscure areas of code. If all that isn't documented at some point, you have a problem. You simply cannot rely on institutional memory for MMORPGs the way you can with single-player or console games. There's no discrete "end" to an MMORPG (until they shut down the server), so Devs will come and go and systems will accumulate and sooner or later the Devs will spend more time trying to sort out what's actually going on than trying to fix whatever is broken.

It doesn't matter HOW you capture your design -- whether it's a awesome prototype, five pages of business speak, or a few paragraphs of "This is a fucking cool idea". What matters is capturing all the shit that occurs between initial design and the ever-moving now. (Or at least the critical bits). Because the guy who did the original concept is long gone. The guy that did the DB design? Moved on three years ago. The guy he trained? Left six months back, after two years of undocumented DB design changes. Combat team? Replaced twice, and something the new team did last week hosed resource spawning but the most experienced resource guy has only been around two years, and he hasn't had to touch that section of resource management since he hired on -- just tweaking stats, not core mechanics. You don't dare roll back the combat changes because it fixed a nasty exploit, but now the crafters are in an uproar because the spawns are broken and nowhere is there any documentation of how the hell the resource code is SUPPOSED to work or why in the hell changing combat code interfered with it.

Relying on institutional memory is something you can get away with sometimes. I don't think MMORPG's are one of them, unless you have a VERY unusual team (CCP comes to mind -- less churn than appears to be normal, even post-release --  I'd be curious to see how well documented their systems are. Given their background, I'd bet money they tend to be more rigorous about it than a lot of game developers) -- even then, I wouldn't rely on it.

But I think that sort of focus is hard to instill. Documenting your code, updating the host of documents explaining how everything works -- that rarely benefits you. It helps other people -- the guy that replaced you, or that jackass over down the hall who never documents HIS fucking work -- so why bother? There's a certain egotism there, too -- the deep belief that you should be able to instantly understand the code, it's design, and how it fits into the overall picture just from looking at it. Documentation is for third-tier code jockeys, not the elite of the elite.

I guess my view here is that I see a lot of what looks like half-assed processes in game design -- MMORPGS, with their release-patch-patch-publish-publish-expansion -- model just make it really obvious. Simple fixes that break seemingly unreleated things, but aren't caught in internal QA (indicating internal QA has NO idea there is a connection between the changed mechanism and the broken one -- and it seems to be a rare game where QA actually bothers to remember that link later). Repeated occurances of the same bug showing up post-fix. Mechanic changes with unforeseen or unintended consequences, LONG lags in fixing bugs and broken mechanisms that are almost certainly due to poor code understanding and not the difficulty of the problem....

Poor processes. Poor engineering. Any sort of art is still, at it's root, a process. I understand the worry that focusing too much on the process can kill the creativity -- but too little focus on the process means that no one's going to see the fun, because it's buried in shit. 

[Viin]

I hate documentation, even if I know there's a good reason.

I work for a large corporation, so there's a ton of paperwork you have to fill out for each project. Spend hours and hours and hours hashing out the docs and whats in them and to what degree (oh no, can't tell development HOW to do it, only WHAT) and blah blah blah. Very frustrating.

We do a lot of documentation on the client side, because we sell access to API and server architecture, so all of that has to be documented for our clients - but other than that, I don't know how useful any of this documentation is for later projects.. I don't think any of it gets reused or referenced. I think part of that is because we have a large complex systems that are maintained by some key individuals that have the native knowledge of how stuff works and how to fix/modify it as needed. However, if those people were to go away I think we'd have a very very tough time getting anyone else up to speed even with all this documentation we do per project.

I don't mind design docs as long as they are kept simple (we call them requirement docs) and I'm not the only one figuring out the product specs based on those requirements (if only because someone on the development side will disagree with my spec or find something I didn't think of).

Has anyone attended the Pragmatic Marketing classes? They have a whole system for Product Managers and their role in the development and evolution of software products. Some of it is pie-in-the-sky (.. in a perfect world ..) but they have some really good concepts of who should own what and what needs to be focused on by whom vs what the majority of time is spent doing.

[Margalis]

Institutional memory is an issue. People should keep track of conversations especially that involve some contention. What oftens happens is that people debate some issue then reach a resoultion, then 6 months later debate it again because they can't remember the original logic. A to B to C back to A.

[Morat20]

Institutional memory is an issue. People should keep track of conversations especially that involve some contention. What oftens happens is that people debate some issue then reach a resoultion, then 6 months later debate it again because they can't remember the original logic. A to B to C back to A.

That I recognize....oh god, do I ever. We've got a pair of people here who are damn determined to sort a list in a certain way, claiming it would increase performance by a few percentage points (it would). The problem -- one they can't seem to grasp -- is that the list is already sorted, and that numerous people require access to that list according to the current sorting method.

No matter how many times you say "If we sort the list that way, yes, we gain performance -- but we break a half-dozen other groups who access that list." they just won't remember.

Skidding back -- no software engineering process is perfect. And they're ALL tediuous, and 90% of it is for the sake of people you'll never work with (the guy that has your job 5 years from now when you're making twice as much and having more fun elsewhere). I hate the bloody things. I hate the reams of documents they produce, and I hate the hour or so a week I spend documenting my work. I feel it's unproductive and useless. But I realize that because of this, I'm saving someone weeks of time a few years down the line -- potentially, at least. :)

I think more gaming companies -- most especially MMORPGS -- need a more rigorous process. If not for initial design, then at least some form of rigorous documentation process as design continues -- or near launch. I watch too many MMORPGs go through the patch process/break/rapid hotfix cycle. SWG was notoriously bad at it (their process as as amateur hour as it gets by the time I started playing) -- they'd patch and break so many unrelated systems, then spend weeks trying to sort it out -- one could only conclude they had no understanding of how their own engine worked. Blizzard is better -- breaking unrelated systems is fairly rare, and they're resolved fairly quickly -- but whether that's because of their long testing periods or because of better processes, it's hard to tell. (Although rigorous QA is part of the process).

Good managers can get their Devs to document their work (or at least cooperate with the poor schmucks doing it) without stifling creativity or filling their weeks with bullshit meetings. But good Devs need to realize that documenting the code is nearly as critical -- in the long run -- as writing it.

[Jayce]

I agree in general with Morat.   

I think some of you are too focused on up front prototype sort of things - and I agree that a prototype is much better than a document most of the time.  I'm talking about documentation of how a game mechanic works, especially complex ones that are not fully explained to the players.  Two examples of what I'm talking about:
- WoW's dodge/block/miss/crushing/glancing/armor/damage calculation that takes place for each swing in a melee fight
- Eve's damage reduction calculation that takes place when a missile hits a fast-moving ship

Without documentation, how does even the original coder remember 6 months down the line what's supposed to happen?  How do you answer the question: "what happens if I move dodge in front of block - does it ruin 5 boss encounters or render a certain piece of armor TEH UBAR?"  Also, how does a QA department create a test case that goes deeper than "Can I shoot a missile at a moving ship and have it get damaged in some way?"

Prototypes work to see if something is fun - ie the early design phase - but for balance tweaking and controlling the chaos inherent when you start tweaking mechanics, I think documentation is pretty indispensable.

[Margalis]

I would develop that sort of thing in stages, iteratively. The problem with doing it up-front is that it is 99% likely to change at least a bit. For example I think a good first draft would be something like:

When a player tries to hit another, the following can occur:

1. The defending player can dodge.
2. If the dodge fails, the defending player has a chance to block. Blocking takes no damage (or some fraction?) and causes wear on armor/shield. Special effects can still trigger on a blocked attack. (Does that make sense?)
3. If neither dodged nor blocked, the hit can do critical/glancing damage.
4. The armor rating of the shield/armor is subtracted from the base damage. (Question: should this be a fixed number or percentage based? Plenty of pros and cons)

Something like that. I have a basic system and have called out a few things that need more depth or prototyping. For example armor subtracting out a percentage of damage is a lot easier to deal with and avoid situations where guys are unkillable, but it also takes out some interesting depth in that attacking rapidly for low damage vs attacking slowly for high damage works out the same with percentage reduction, whereas they are very different against a fixed reduction. That is something I may list some pros/cons for and put off the decision a bit.

For something like do specials trigger on block most of that would just depend on what feels right in gameplay, it doesn't really matter that much.

I might also list out how often I think these things may occur. For example if a very nimble player is fighting a very clumsy one of similar level do they dodge 30%? 60%? But again those numbers would be tweaked multiple times during testing.

Basically at first rather than make decisions I would want to get the general idea and establish the framework for making those decisions. Call out pitfalls, things we want and want to avoid, etc. From a programming perspective it would be fairly easy to take the bullets above and make a tweakable system out of them.

At some point the example formulas should be written down for future reference, but I would do that as I refined the code, not before I started it.

Those types of decisions would have to be nailed down before full-scale content creation most likely. As you say, you can't decide to swap dodge/block on the last day. But you could toy with it all you wanted until that point.

[Xilren's Twin]

zombie post:

Lum linked to a nice write up from Brandon Reinhart, a former SWG designer giving some how to advice on design doc's over at his site, so here's the linky and below is the nice cut and past :)

Things to do before you write.

1. Determine your audience.

Before you start to write any kind of official project document, it always makes sense to think about your target audience. Who you write for affects how you write. The first thing your audience can tell you is what you should include and what you should not include. If you're going to be writing a document for other designers, you know you won't need to include explanations for terms like "DPS." Whereas other audiences like artists may not necessarily have a grounding in all the MMOisms. Another thing your audience can help you with is your tone. Programmers generally want things explained very directly, to ease their path to implementation. A presentation to your publisher's producers, on the other hand, is going to require a more visceral style. No matter which audience you are writing for, I highly recommend you use an authoritative tone. Instead of saying "the system SHOULD do X" or "the system MIGHT do X" say "the system WILL do X." Even conditions can be presented authoritatively: saying "Option 1: The system will do X" and "Option 2: The system will do Y" is better than saying "The system might do X or Y."

(For this blog post, I determined that my audience would be readers casually interested in MMO design or QA/CS type employees looking for information that might help them get an edge up on design jobs.)

When you write a system design doc, you'll probably be working from a template. The template will be designed to give each technical doc a specific structure, to aid the team in producing consistent work. The template will also probably imply (or explicitly include) a particular audience. In the case of a technical systems design doc you have two audiences:

Other designers.

The first people to read a system design doc will be the other designers on the team. They'll be adding their own comments in the margins, sending you emails with ideas, suggestions, or criticisms, and contributing to the development of the system. The system doc you write may actually be given to another designer in a kind of round-robin review. Knowing you're writing for designers gives you a good idea of what you don't need to include: exposition on why certain mechanics exist, definitions of common terms, etc.

Programmers.

This is your most important audience. It is also your final audience, whereas designers are a transition audience (they help you work toward the final document and the programmers are the ones who receive the final document). The programmers are going to take your document and build a system based on it. This means requirements! Lots and lots of requirements. Rules that describe everything the system does and needs. It also means clarity and structure. We'll get into the specifics in a bit.

2. Prepare an outline.

Once you know your audience, outline your document. A company supplied template will probably provide the best initial outline. Break down your system into subsystem chunks and create quick outlines that cover the core functionality. This will help you figure out the best structure for your document. Sometimes talking about a system in a linear fashion isn't the best approach. Use your outline to find a way to build up the discussion of your system from simple elements to a complete picture.

The elements of your document.

Now you're ready to write, so let's talk about what your document should contain. I'm not actually going to present the template Spacetime Studios uses, but I will talk about the components. If you're interested in applying for gameplay systems design jobs, you might consider creating sample design documents that describe systems you've invented. That way you not only demonstrate your creative thinking, but you also show structured thinking. (We'll talk more about design portfolios at the end.)

Element 1: Overview

The first thing in your doc...well, other than the table of contents...the first thing in your doc is an overview of the system. This is where you provide the context for everything that comes after. The overview briefly describes what the system does and in some cases why the system exists. If the system is a solution to a poorly understood problem, or if the system is complex, you can use a more lengthy overview to explain WHY. Generally, though, you want the overview to be brief. Other sections of the document will go into much more detail. Putting too much detail in the overview would just be redundant.

Element 2: Goals

The second element of a technical design document is a set of goals. Goals help give a direction for the system. They provide a way for the designer to very quickly explain where they're coming from. For example, if you're working on any variation of the standard MMO you're going to need an items system. Items systems can be very complex, with hundreds of possible attributes or functions. That complexity might actually exist for a reason, like to provide variety in the items-as-advancement mechanic. A goal for the system, then, would be complexity. Declaring it as a goal and explaining why and what you mean provides a direction for the system. In our game, our items systems' goals are scalability, abstraction, and complexity. Two of these goals (scalability/complexity) are to achieve gameplay objectives and one (abstraction) is to achieve a content creation objective. Some of your goals might also be about how the game is built, not how the game is played.

Not all systems need "ideological" goals, like the ones above. Sometimes your system's goal is just "solve problem X." Direct declarations of intent are fine, but thinking about your system in ideological terms can help you explain why you chose to solve the problem the way you did. Programmers will be on the lookout for simpler implementations than the one you suggest. That's their job. Efficiency is one of their ideological goals. In order for you to properly discuss alternatives, you need to have a very good idea of why you are taking a certain route. Understanding your objectives will help you separate bad alternatives from good ones.

Element 3: System Requirements

This is the meat of the document. Your system requirements are an enumerated list of everything your system needs to work. You will use the requirements list to develop a complete mental map of your system so that a programmer can create the code.

- Break requirements up by subsystem.

Instead of providing a massive numerical list of requirements, structure them by subsystem. Figure out the big chunks of functionality that make up your system and use those to provide a top level structure. For example, in a grouping design doc we might have top level subsystem requirements lists for "Sending Group Invitations" and "Leaving a Group." It should be pretty obvious what the high level pieces are, but sometimes you'll find that using this approach leaves big gaps in your explanation. In particular, you might find that you need to establish a foundation for your explanation. Continuing the example of groups, we might need an initial section explaining just what the hell we mean by groups in the first place. Use your foundation to define terms and system-wide limits (like max group size).

- Don't dig around beneath the hood.

It's important that your system requirements avoid suggesting technical implementations. The purpose of your document is to describe the system, not hand the implementor a guide to how you think things should work under the hood. The implementor doesn't care if you think that attributes should exist in a doubly-linked list to enable faster searching during the item equipping process. Suggesting technical details breaks a critical level of abstraction between the system as an element of gameplay and the system as an element of the game engine. It distracts from the important explanation of the game's functionality at the level of design. Let the implementation team figure out how to make your system in a later pass. This is true even if you are one of the implementors.

- Define new terms and use them consistently.

As you write requirements you should define any invented terms as you go. If you are going to use the term "Content Transition Region" as a buzzword-code for a particular feature of the system, pick it out with a definition. Then use that term consistently. Don't use "Content Transition Zone" or "Content Transition Primitive" if you've already defined the term with "Region." Inventing terms is fine: it can help simplify the explanation of a system, but be wary of how you use words and try to reduce the chance for confusion. If "region" already has some kind of implied meaning in your game, be careful about arbitrarily co-opting it for use in another context. This is a good way to confuse the hell out of programmers and end up with completely unexpected problems.

- Organize requirements into levels of detail.

Each requirement describes a need. These needs are requests for functionality. They can get very complex very quickly. Try to use an outline form to organize the elements of your system into layers of increasing detail. For example, if you are talking about a level based advancement mechanic you might have a series of requirements that look like this:

1. Gaining a level. Upon meeting a level threshold, the character gains a level.

             a. Increment her level and start using it in game formula.
             b. Display a particle effect and play a sound.
             c. If the player is in a group or guild, print an announcement to his group and/or guild chat channel.
             d. Apply bonuses to the character’s stats. See the statistics system section B.
             e. Heal the character’s pools to full.

You'll want to balance the depth of your outline with the detail provided. If an element of the requirement involves a deep explanation, consider breaking it out and moving it to a higher level of the document later on like a subsystem explanation.

- Write to the appropriate level of complexity for implementation.

You should supply requirements appropriate for the scope of implementation and that's going to depend a lot on how your company works. If your company likes to take big, detailed systems and do the entire thing top to bottom, then your system docs need to be very detailed and cover a lot of contingencies. If your company implements in planned iterations, you'll generally only write to the depth of the next iteration and slightly beyond. For example, when prepping a brand new combat system for an iteration based implementation process, you would only go into detail about the basics of the system like dealing damage and resolving hits. You wouldn't burden the initial document with a committed set of armor mitigation equations. You might, however, provide direction statements like "For the future: Before damage application, damage will be mitigated according to a scaling factor called the 'Armor Mitigation' value. This value may be determined by..." These direction statements can be italicized or greyed out to indicate they aren't intended for the first iteration. The objective of the direction statement is to prepare the programmer for the future evolution of the system. This enables them to do their own design in a way that anticipates change in the right parts of the code.

If you do develop in iterations, you'll revisit the document after playing with the initial implementation. Now that you can shoot and deal damage, what's next? Armor mitigation! Time to add those details to the document... and so on until you have a rich combat system.

Element 4: User Interface Requirements

I suggest keeping your user interface requirements in a separate section. It helps a lot when it comes time to figure out asset counts. It also gives you an easily detachable mini-doc that you can send to artists. UI requirements are generally pretty self-explanatory. Any menus, windows, HUD widgets, and other input-interactive elements of your system would be detailed here.

Provide mockups! Microsoft Visio is an excellent tool for building quick UI mockups, but there are other tools that can help do the same. UI requirements are inherently visually oriented, so creating even the simplest sample of your inventory window or your character sheet will help fit all the pieces together in the head of the reader.

If your system comes online, update your doc with screenshots of the UIs. That way you can keep a handy history of the evolution of your system's visual elements. Being able to compare the various stages of your system's UI evolution can help you avoid jumping the complexity shark as you add new features.

Element 5: Tools Requirements

If your system requires any kind of content or data you'll probably want a tool. You do NOT want to have to edit flat text files for every item or creature in your game. Yuck! Believe it or not, a lot of well known, huge MMOs do exactly that. Ick! Create a section that provides the tools requirements for your system. How does the editor interface work? What kind of data views are you going to need? Think about the future! Not only are you going to be creating new content for your system, you're going to be maintaining that data as well. Using items as an example again, you know that you aren't just going to need to be able to create individual items, but you'll also probably want a spreadsheet style view so you can make mass changes to lots of items at once.

If your design group develops a habit of providing tools requirements with each iteration of a system, your programming team will develop the infrastructure needed to support it. (Obviously, this should be established at the production level as a shared goal for both groups.)
You'll find that you suddenly have the ability to request tools for relatively minor systems, because the support code to build those tools is already done.

Tools are the make or break point for MMO quality. You either have the ability to make content or you don't. If your game's editor is called "Textpad" you don't.

Element 6: Service Requirements

Holy crap, you will not believe how many designers there are that fail to think of their systems from the perspective of the lowly Customer Service rep or Quality Assurance testgrinder. If there is any one thing that will cut thousands of dollars off the cost of development it's proper support for service requirements. They break down into two categories:

Quality Assurance

Lots of people are going to be testing your system. The first one should be you. QA does not exist to find out your system crashes the server upon BOOT. They exist to find the unobvious bugs. You (and your implementor) are responsible for the obvious ones. If you don't provide proper QA commands and testing aids you make both of those jobs harder. The QA service requirements should describe all of the commands and hidden features necessarily for detailed, repetitive testing. Not only will this make it easier for you to find the flaws in the latest version of your system, but the QA team might just buy you a beer. The more you enable QA to do their job, the more they will give you meaningful feedback that will help you improve your design.

Customer Service

Bugs will slip onto live servers no matter how good you, your programmers, or your QA team is. It just happens. Your company might have one hundred people to throw at finding bugs, but the player base has MILLIONS. The key, then, is to mitigate the amount of damage bugs do to players. This means providing Customer Service with the tools to fix the problem.

CS commands should scale with responsibility. Your basic CS guy might be able to address really basic problems with your system, or snoop for bad data. Your CS manager will have the power to effect greater change. This goes all the way up the chain to you. You WILL be called on to fix the really bad bugs. Many companies give their designers god-fobs for this specific purpose. Those that don't may call you in to advise whom-ever they trust with such lordly might. Do yourself and your CS team a favor: provide a spectrum of tools to examine system data and correct it. (Work with your programmers to define a way of giving these tools security levels.)

Service requirements are written just like any other requirement. State the need. "A command to instantly kill a player." Or whatever.

The key to being successful in the MMO industry is to make money. You aren't going to be making much money if players are quitting your game out of frustration with unaddressed bugs. Look at your game's average CS call time can help you figure out if you've got a CS problem. Often the calls go long because CS isn't able to easily help the angry player. The more you anticipate how your system will fail and how it can be fixed, the more likely your CS agents will be to resolve the player's problem.

CS is it's own industry. This is not meant to be a complete discourse on CS by any means.

Element 7: Logging Requirements

Detailing what your system needs to log will help you track down why a particular bad thing is happening. It also fuels metrics. This section should describe what kinds of logs your system should be able to provide and what kinds of data other systems might want to know about it.

Logging isn't just a passive exercise. You may very well want to describe some push-logging requirements. This is great for finding potentially toxic data (data that could crash the server and deny service) or for finding cheaters. For example, if your character stats system, combined with every other system that modifies stats, won't ever allow a player to legally reach 300 strength, then you should probably WARN SOMEONE when a player gets more than 300 strength. You might have found a cheater. You've certainly found a bug.

It makes sense for programming and design to establish a plan for push logging at the production level. That way you can describe push logging requirements with multiple layers of visibility. Maybe some warnings go to coders, others go to designers, others go to whoever has the "OMG THE SERVER IS DEAD OR DYING" beeper. If someone dupes up a fresh 2 billion gold, you're probably going to want to put a stop to that shit RIGHT AWAY. :P

Element 8: Metrics Requirements

Metrics are used to discover trend data in your system. This subject is on the cutting edge of MMO systems development, so I don't know if I want to go into too much detail. Suffice to say that you want to find out what kind of information-over-time your system is capable of producing. What are the indicators you'd like to monitor during testing or beta, that will help you figure out which knobs to turn?

Lots of companies are developing strategies for analyzing metrics. Some of them are just reading tea leaves, others are finding really meaningful patterns. There's a lot of potential for those patterns to enable better MMO design on a significant scale. Are metrics the key to grokking the MMO at a deeper level? A lot of smart people say yes...

Element 9: Risk Analysis

Wee! Risk analysis! This is where you should get into explanations of all the potential bad stuff that could come out of your system. Does your system require a lot of content in order for it to reach some critical mass of success? That's a risk. Try to figure out where the critical mass is. If your system is really experimental, use the risk analysis section to look at alternatives in case you miss.

Assets are high risk. Take time to figure off how much asset creation time you're biting off with your system. Consult the artists. Plan a production pipeline for your system. Proactively mitigate the risk (costs) associated with generating art & sound by planning for it.

Find ways to make your system scalable. If you identify a particular series of assets as a risk, see if you can suggest an alternative that cuts out a chunk of the series.

Be honest with yourself. Don't ignore scary possibilities because you fear that your system will be rejected. If you can't face the real impact your system might have on the game, you aren't going to be doing your team or the project a service. Your readers are smart, they'll probably see the big risks anyway and you need to understand those risks to discuss them.

Sometimes you'll look at your objectives & goals, your system, and your risks and say "this just ain't worth it." If you do, shelve the system and move on. You might just think of a better way to achieve those goals at a later date. (Obviously you can't shelve fundamental systems like combat. If your fundamental system has too many risks you either move forward or revise it. If you move forward, then those risks are fundamental to your project and everyone should be aware of them. Example: Making a combat intensive game with a combat system that relies on complex physics has a big risk associated with getting the complex physics working in an MMO environment. That means your game is really about complex physics (although that was probably already obvious...it's just an example).

Element 10: Use Cases

Take some time to provide scenarios that employ your system. If you're writing about a grouping system, show how a player would join and leave the group. Talk about what the player sees and does and the order in which everything happens. Use cases clarify all of those requirements by giving a context for the system.

Element 11: Visual Aids

Diagrams are a great way to illustrate how a system is supposed to work. In an advancement system, you might diagram the level advancement curve to illustrate the concepts involved. You can either accumulate your diagrams in one spot, or inject them in the appropriate places in the document. Either method is fine.

Revising your document.

Take time to review your document periodically as you write. You might find that your risk analysis or tools needs suggests new requirements for the main system. Build up to the final description.

Review the document with your lead and any programmers acting as technical advisors. This will help you get some objective perspective on your style of presentation and the content of your document.

Keep the damn thing alive. There's no point to spending all this effort detailing a system, only to ignore the document once the first revision hits your test server. If changes are made to the system, make sure the document reflects them. If you are moving into a second level of detail, update the existing document instead of creating a new one.

I'd even suggest recording major design or technical problems you've encountered in your system doc. If you find a flaw in the system and you come up with a spot fix, don't just update the requirements to reflect the new functionality. Record the impetus for the fix. This will really help you avoid reintroducing the problem later.

Conclusion...

I'm going to draw it to a close here. That's a big ass post. Should at least give you a sense of direction for developing a good system design description. Use this method to create an impressive design portfolio. If you want to get into gameplay design and you have an idea for a game system, document it! Demonstrate that you have production skill: that you understand how to structure an idea so that it can be implemented by someone else. If you want to go one further, provide example asset lists that detail the textures, skins, sounds, and other art pieces that would be needed to fill out your system with content.

You'll be surprised how much of an edge this will give you over other design candidates.