How to Write Great Design

Documents
Damion Schubert
Bioware Austin

www.zenofdesign.com

About Me
MMO Designer for 10 years
Lead Designer for most of them
Used to working with very complex systems
Grew to appreciate good documentation
processes.
Found being the doc guy very good for my
career
Still learning about how to do it right
What I hear
Design documentation is a waste of
time
No one reads design docs.
My programmers find reviewing design
documents a total time sink.

This is probably a statement about your
documentation, not a true testament of
documentation in general.
The Harsh Truth
All designers should want to share their
ideas
All programmers (and other team
members) should want to know what
theyre building.

On the other hand, most design
documentation isnt very good, and most
documentation processes ignore the
iterative nature of finding fun.
This Talk
Goals of the design document
Why is good design documentation rare
Rules of writing game design
documents
Tips for leads building a game design
documentation process
Presentation Focus:
Executive Summaries/Vision
Documents
Design Overview Documents/DDRs
Test Plans
Systems Design Document

Talk is not about:
Goals of Good Docs
Capture design consensus
Primary vision conduit between
departments
Aid in scheduling
Offer focus
Give visibility to future
dependencies and design conflicts

Why is good design
documentation so rare?
Design docs for most games deal with
complex, interconnected systems.
Designers tend to overdesign.
Systems take less time to design than to
build.
Big Book of Stupid
Most design docs dont embrace
iteration.
Most docs are rarely kept up to date as
the project progresses.
Rules of good
Design Documentation
What other devs say:
Just give me
something thats
short, targetted, and
up-to-date.

I just want a bullet list
of things to do.

Short and accurate,
easy to find the
code bits.

1. Know your Target
People interested in a design doc:
Design team. To achieve design
consensus.
Programming team. To build the game.
Producers. To schedule and go get
money.
QA. To build test plans.
External partners. To reach quota of
annoying demands.

1. Know your Target
Programmers are the most important
target.
Its how the game gets made.
Often, other documents are more useful for
other audiences anyway.
When in doubt, make the docs serve the
programmers
Ask the programmers what they want
If they say to ignore one of my rules, do it!

2. Keep it Short
Short documents are:
Easier to read
Easier to write
Easier to maintain and keep up-to-
date
Easier to handle politically
Less likely to be contradictory
More likely to be simple designs
2. Keep it Short
Kill the fluff
Kill empty sections
Kill cut and paste stuff
Kill unnecessary text of obvious
systems
2. Keep It short
Guild Invitation Confirmation UI. Players get a Confirmation
UI when creating a guild. This asks Do you really want to join
this guild? and has an ok button and a cancel button.
OK Button. The confirmation UI has an OK button, which
confirms the invitation of the guild.
Cancel. The confirmation UI has a cancel button, which
prevents the guild from being formed.
Close button. There is an X button in the upper right
hand corner of the UI, which is identical to hitting the cancel
button.
Esc. Pressing escape will cancel the transaction, and
performs identically to hitting the cancel button.
Too Long
2. Keep It short
Guild Invitation Confirmation UI. Players get a confirmation
dialogue when invited to a guild (see CommonDialogs.doc).
Better
2. Keep It short
Crafting Tithe. Hephaestus, the god of the forge, has instituted
his will upon the craftsmen of Athens, and all are humbled by
his greatness. As such, any players who wish to craft any items
must pay a tithe to the temple of Hephaestus to earn his favor,
unless that player has found an item like the Hammer of the
Gods, which allows the player to bypass these tithes.
Who cares?
2. Keep It short
Crafting Tithe. Players who craft items must pay a cost in gold
(a tithe to the local temple) when crafting.
Bypassing tithes. Certain tools allow the player to bypass
the tithe.
Better
2. Keep it Short
Remember:
Programmers almost always want a
short bullet list
(They kind of like checking things off
of lists)
3. Prioritize the Design
Give the features a priority, break
them into phases
Be sure document clearly
separates out later phase features.

3. Prioritize the Design
Players can equip items on the inventory screen.
Equipped items change the players combat stats.
Player equipment is visible when worn.
Player equipment may be enchanted with magical
effects
Players may have their guild insignia drawn on their
player shields.




Wrong!
3. Prioritize the Design
(Phase One) Players can equip items on the inventory
screen.
(Phase One) Equipped items change the players
combat stats.
(Phase Two) Player equipment is visible when worn.
(Phase Two) Player equipment may be enchanted with
magical effects
(Phase Four) Players may have their guild insignia
drawn on their player shields.




Still not great


3. Prioritize the Design
Players can equip items on the inventory screen.
Equipped items change the players combat stats.


Player equipment is visible when worn.
Player equipment may be enchanted with magical
effects
Players may have their guild insignia drawn on their
player shields.


Basic Equipment (Prototype)
Advanced Equipment (Phase 2)
Guild Insignia on Equipment (Phase 4)
Better
3. Prioritize the Design
Phase 1: Prototype feature
(necessary to validate or demo the game)
Phase 2: Core feature.
(features and tools that hold up content creation
go here)
Phase 3: Must be in shipped product
(includes features that depend on priority 2
features)
Phase 4: Wishlist, possibly expansion
Phase 5: Yeah, right
3. Prioritize the Design
Prioritization is across the project,
not the feature an entire feature
or document may be full of phase
2, phase 3, or phase 4 features.
4. Illustrate
A picture is worth a thousand words.
Tactics:
Screens of other games with similar
features.
Visio diagrams
Example text
4. Illustrate

Players can remove a skill in their skill tree by going to a
special NPC (the mindwiper) and selecting that skill.
Removing a skill has a monetary cost in credits.
The player cannot remove a skill that is a prerequisite
for another skill in his skill tree.
Joe Bob decides that he wants to unlearn Basic Psionics
and Advanced Psionics, so he goes to a mindwiper. He
tries to remove the Basic Psionics skill tree, but the
transaction fails, as it is a prerequisite for Advanced
Psionics. So Joe Bob unlearns Advanced Psionics and
then Basic Psionics. In this case, both boxes are
successfully removed.

Example
4. Illustrate
Whats wrong with this?
The more abstract a picture is, the
easier it is for a reader to project his
own viewpoint *
Assuming you have a competent, well-
paid UI artist, you want to give his
imagination room to breathe dont try
to do his job!

* Understanding Comics, Scott McCloud. I seriously hope
everyone has read this one.

5. Dont tell others How
to do their jobs
Orcs
Elves
Dwarves
Hobbitses
Puma People
Kraven's Reputation
Better, believe it or not!
5. Dont tell others How
to do their jobs
Quests.doc

Quest Variables will be stored in a linked list of
bitvectors on the character object.
This is not your problem!
5. Dont tell others How
to do their jobs
Quests.doc

Memory considerations of quest variables.
There will be approximately 2500 quests in the game.
Players may have 20 open quests at a time.
Players can make up to 10 decision points in one
quest, the status of which must be stored until the
quest is completed.
Players may find content later which is unlocked by
quests they have already completed the completion
state (and outcome) of a quest must be stored.

This is your problem. Let coders solve it.
6. Use user stories
Independent doesnt overlap other user stories
Negotiable details and implementation are less
important than end user satisfaction.
Valuable written with the end user in mind.
Estimatable detailed enough for programmers to
architect & schedule
Small no more than a week.
Testable design and programming can agree
when its done.
SCRUMs rules for User Stories,
Note the INVEST acronym.
6. Use user stories
The player hears a sound effect when he gains a level.
Too small!
The players can elect a new space ambassador .
Too boundless!
When the player gains a level, he hears a sound effect,
sees a particle effect, gains 3 attribute points, gains 5 skill
points and gains access to a prestige class if he is level 10.
Too long!
6. Use user stories
The player gains a level when he crosses the
experience point threshold.
The player hears a ding sound effect.
The player sees a particle effect.
The player gains 5 attribute points to be spend on his
stats.
The player gains 3 skill points to be spent on his skill
tree.
If the player has reached level 10, he can acquire his
Prestige Class (see PrestigeClasses.doc)

We use 1 user story with subrequirements,
equal to 2-5 programming days of work.
Note the player starts each one.
7. Separate Code from Content

Crafting tools. Some crafting skills will require crafting
tools to be used, or the player will get an error message
saying he cannot use that skill.
Blacksmith. Using blacksmith skills requires a
blacksmith hammer and tongs. Players may eventually
find more advanced hammer and tongs, that give
access to more crafting options.
Tailor. Being a tailor requires a loom.
Alchemy. Alchemy requires a test tube set. Players
may eventually find more advanced test tubes, that
give access to more crafting options.
Sculpture. Sculpture requires a hammer and chisel.


Scary wall of bullet points!
7. Separate Code from Content

Crafting tools. Some crafting skills will require crafting
tools to be used, or the player will get an error message
saying he cannot use that skill.
Advanced tools. Some crafting skills let the player
craft more powerful items with more powerful tools.


Skill Tools Advanced Tools
Smithing Hammer and Tongs Yes
Tailoring Loom
Alchemy Test Tube Set Yes
Sculpture Hammer and Chisel
Crafting Skills and Tools
Only two requirements easy!
7. Separate Code from Content
Dont make people hunt for the
information they want.
Separate content into appendices,
or into tables.
8. Invest in a good Format
Use a team template
Change the font
Use horizontal lines
Use callout boxes for example
Use bullet lists
BUT dont be a slave to your format
Viva la Difference
This is the default Microsoft Powerpoint
template
Not very good looking, is it?
Taking a little time to change out your fonts or
add a watermark can have a huge impact on
how professional your documents feel.

9. Use Clear Terminology

This spell has a high DPS,
but also has a hate
reduction component to
reduce aggro in raids.

There can only be six
spawn agents per
superchunk.
Dont assume what your readers know!
9. Use Clear Terminology
Use plain english
Avoid Wonky terms
Avoid company-specific terms
Use new terms consistently
Consider a glossary

10. Kill Redundancy
Duplication is the devil, leads to
confusion, update errors.
CombatStats.doc

Strength increases the
players damage by
STRENGTH/2.
Dexterity increases the
players accuracy by
DEXTERITY/3
Body odor reduces the
players chance to seduce
NPCs by BODYODOR/2
Items.doc

Strength increases the
players damage by
STRENGTH/2.
Dexterity increases the
players accuracy by
DEXTERITY/3
Body odor reduces the
players chance to seduce
NPCs by BODYODOR/2
Redundant Department of Redundancy !
10. Kill Redundancy
Duplication is the devil, leads to
confusion.
CombatStats.doc

Strength increases the
players damage by
STRENGTH/2.
Dexterity increases the
players accuracy by
DEXTERITY/3
Body odor reduces the
players chance to seduce
NPCs by BODYODOR/2
Items.doc

Enchantments on an item
can increase the players
stats when worn. See
CombatStats.doc for more
details.
Make one doc the owner, point others to it.
11. No Weak language

Players might be able to woo NPCs of
the opposite sex.
In the future, we may add the
functionality to increase your chances to
woo women by playing sappy love
songs.
If this is implemented, maybe players
can write their own love songs.
No!
11. No Weak Language
Romancing NPCs (Prototype)
Players can attempt to romance NPCs
of the opposite sex by dialogue options
Players can also attempt to romance
NPCs of the opposite sex by serenading
them with songs theyve learned.

Advanced Romance (Phase Four)
Players can craft their own songs for
use in the romance system.
Better!
11. No Weak Language
Use strong, declarative language
No maybe, could, might
Even avoid may.
Dont be ambiguous
Dont say we
Choose a direction
Move maybe features to later phases.
12. Capture your Reasoning
But compartmentalize it.

Players may not place items on the
ground. This is to help reduce visual
clutter and ensure that players may not
be disruptive through the placement of
hundreds of items.
No!
12. Capture your Reasoning
But compartmentalize it.

Players may not place items on the
ground.

FAQ: Why cant players place items on
the ground?
This is to help reduce visual clutter and
ensure that players may not be
disruptive through the placement of
hundreds of items.
Much better!
12. Capture your Reasoning
Capturing your reasoning is especially
useful for longer projects, where the
team may literally forget why they chose
one side or the other.
Capturing your reasoning, by extension,
reduces the number of times
contentious issues are reopened.
Tips for Leads
1. Embrace Iterative Design
Design the next immediate phase to
fine-tooth detail
Design far off phases to man-month
degree
Dont allow designers to emotionally
invest in far-off features
Revisit documentation as the design
shifts and iterates.
2. Make it Searchable
Design docs will only be used as a
reference if the user can find what he
needs.
Possible means:
Wiki
Desktop Search
Design Bibles

3. Automate what you can
Need proof?
Thottbot, Wowhead, Allakhazam
Advantages of Documentation
Automation:
Accuracy, even postscriptively
Searchable
Easy to add auditing and reports
4. Design Documentation
is a collaborative Process
Designer/Lead Design Setup Meeting
"Experts" Brainstorm
Document First Pass (Lead Designer Review)
Design Team Review
Senior Leads Review
Approved!
("Publish to team")
Design documents
written in a vacuum
almost never survive
contact with the
enemy.
5. Always start with a Kickoff
Meeting
Designer meets with Lead
Designer, and answers these three
questions:
What are the goals of this system?
What are the questions this document
should answer?
How complex can this system be?
The kickoff meeting
What are the goals?
Justify the system
Help decide fencepost issues

Example: the following two goals are
worthy, but contradictory, unless the
design plans for it up front.
Crafting is a sideline activity, to fill
downtime, and can be done on the field.
Dedicated crafters can own their own
forges and blacksmith shops, and achieve
fame and fortune serving other players.
The Kickoff Meeting
What questions does document this
answer?
Since all systems touch each other
eventually, important to decide where a
document ends.
Allows leads to schedule the documentation
process.
Prevents jumping the gun
Prevents design claim jumping
Highlights phase 1 features
The Kickoff meeting
How much complexity?
Token Representation. We just want the
bullet point on our box
Competitive. We want what the market
leader has with minor tweaks, but we dont
want to be too risky.
Alternative. Nothing too big, but definitely
different from our competitor.
Innovative. This feature will crush
opponents, and we will hear the
lamentations of their women.
6. Have an Approval Process
Should telescope out
Lead Designer Approval First
Design Team Approval Next
Senior Leads/Cross-Team Approval Next
This approach allows the design team to
speak with one voice about a finished design.
Is always tough to get up and running, but
usually accelerates once teammates find
value.

7. Mandate expert consultation.
MANDATE that your designers do not work in
a vacuum on any document. They should
seek out resident experts.
Other designers on the team.
The engineer who is building the feature.
Artists or programmers with unique expertise
For tools, the customers
Members of other project teams if their insight is
particularly valuable.

8. Have a visual Method of Tracking
Progress
In Queue In Progress LD Review
Team Review
SL Review
Approved
(I like using post-it notes)
9. Have a change Process
Designs will shift as the game iterates. A
process is necessary to ensure that design
changes are disseminated to decision makers
on the team.
The Lead Designer can usually act as the
arbiter of when the Senior Leads need to be
notified of and/or approve of a major change.

10. Occasionally audit the process.
Design documentation procedures must work
for the team. If the team sees the
documentation process as oppressive, the
design documentation process will end up
subverted.
Never lose sight of your goals:
Short
Up-to-date
Programmer Friendly
Every 4-6 months, ask yourself (and your
programmers) whats working and whats not.

Questions?