I’ve written an alarming number of words of design specification over the past 15 years. These are, in no particular order, my guidelines for effective spec writing.
You Are Not Your Spec
Seems obvious, but this is the first thing to realize about writing any design document. Your ego is not part of the process. Your name won’t even go on the spec. Attacks on your design are not attacks on you.
Let’s get it out of the way: your spec is probably stupid. It’s probably obvious, it’s probably trite, it’s probably unbalanced and demonstrates a profound lack of design skill. It’s probably boring and will likely be the reason people cite when they quit the game in anger.
You will need, more than anything, to detach from your emotional investment in the document. You worked hard on it! It is valuable to you!
It might be worth the exercise to write a spec you’re moderately proud of, and then delete the whole damn thing. Then start over. Because it’s literally just a document. It is not your identity.
Specs Are Not Arguments
Nothing in your spec should, unless you’ve explicitly been asked to do so, explain why the feature is necessary. Nothing should argue that the feature is better than another feature specified or implemented elsewhere.
The point at which you’re sinking a lot of (valuable and therefore expensive) designer time into writing a long, detailed document? It comes well after those arguments. Before you write anything, you should have already shopped the idea in simple, loose form to all the stakeholders, and gotten their buy-in.
Let’s unpack that, actually.
Simple: if your idea can be explained only by reference to a chart and three pages of careful walkthrough, you need to pull back to a higher-altitude view. Your overall plan should fit in just a couple of sentences. The specifics can wait.
Loose: when you actually write the spec you should be absolutely precise and leave no room for interpretation. Before you write it? It’s fine to say ‘we’ll figure something out’ as the answer to just about anything. Handwaving is fine. Ambiguity is fine. ‘It should fall off at some rate over time’ is fine.
Stakeholders: Just figure out who the people who care are: who has to do work to make this happen? Who has to fit this into other things they’re building or concepting?
Buy-In: getting buy-in is as simple as asking all the stakeholders if the plan sounds reasonable. If they say yes, great! You’re ready to write the spec. They’re not going to say yes. This is probably the most important part of this whole process: listen to why they don’t like your plan, and imagine the plan as envisioned by them. It is always going to be the case that at least one of your ideas is not as good as at least one of their ideas. Start with that assumption, and see if you can figure out which one it is.
Not every issue needs to be resolved before writing the spec, and you can decide to work out some of the disagreements during the review process, but the fundamental concept should be agreed on by everyone before taking any further steps.
Specs Are Blueprints
The spec has two objectives, and the order matters:
- Be technically correct
- Be easy to understand
The first one is by far the most important consideration. Your spec should be precise and accurate. There is no room in a spec for interpretation, creativity, loose language, wishy-washy commitments, and so forth. If you feel like you’re not certain about something, don’t put your uncertainty in the document. Put it in a comment, and specifically ask for feedback on that portion of the spec.
Words you should never say: ‘That’s not exactly right, but you get the idea.’ It has to be exactly right. Do not expect someone to ‘get the idea’. Do not expect the people involved to just do the ‘right’ thing for the project. What is obvious to you is not necessarily obvious to anyone else.
I like to think of a spec as a blueprint for a house under construction. Everyone basically knows what a house looks like, how it’s laid out, and what rooms are in a house. But if you give someone a piece of paper and a pencil and say ‘draw the floorplan of a house’, you’re going to get very different results from an architect than from an average person. The architect will remember to put bathrooms in the house.
A blueprint has every single detail, every dimension, every support beam and nail and piece of drywall. This is because the people doing the hands-on work to actually build the house don’t necessarily know why a decision was made, and so aren’t able to fill in any blanks. The architect could hang around with them every day, explaining the blueprints when they find ambiguities, but that’s a waste of everyone’s time. And ‘I didn’t feel like drawing all the plumbing that goes to the bathroom’ isn’t going to get any toilets flushed.
Don’t say ‘the enemy’s stats will increase at a couple of points during the fight.’ This is a blueprint. Which stats increase? How much do they increase? What triggers the increases? Does any of this vary? If so, how does it vary and what causes that?
Choose your language carefully. There is no place for rhetorical flourish in a spec. Things you write should have only one way they can be read. If there’s ambiguity in terms or how you’re using them, either more carefully define your terms, or add more text to clarify exactly what you mean.
I want to expand on ‘define terms’, actually. If you need to refer to a concept more than once, you should create a unique term for it, define that term early in the document, and use that term consistently. If, for instance, you want to talk about how far different characters can throw a rock, and there are a handful of other objects that can be thrown, you should define the term ‘throwing distance’. Call it out with italics or bold, so that it’s clear that it’s a term and not just casual language.
If your spec relies on terms or systems defined in another spec, link the other spec at the moment the information is needed, as well as any time you think the reader might have forgotten. You can’t really link a required spec too often.
Things to leave at the door: why did you design it this way? How else could we design this system? Blueprints don’t contain explanations of aesthetic choices or alternate house configurations. Your spec should not, either.
A good conceptual rule to follow is this: imagine you handed your spec off to a go-between, who then handed your spec to an engineer you’d never met, who had no contact with you. Is your spec thorough and specific enough that the engineer could implement the feature exactly as you imagined it, without further input from you?
Specs are Single Purpose
Don’t design two systems in one spec. If you find that you’ve put a second top-level header in your document, and the stuff under it is largely unconnected to the first half of the document? You’re writing two specs. Break one out, link them where needed, and design them separately.
It’s useful to think of design in terms of object-oriented programming. Narrow the problem down to the smallest unit that makes sense, and then work only on that. If it needs to refer to other systems that don’t yet exist, don’t design those systems. Just leave a note for yourself to come back and flesh out the connections to that other system, and assume the broad shape of the intended system.
The reasons for this are actually really straightforward: an engineer opens a spec and expects to see one complete set of features and requirements for one element of the game. If there’s a second element of the game tucked away in there, the engineer is unlikely to remember that. Later, when she’s looking for the design doc for ‘Sprocket Installation’, she’s not going to think to look in the middle section of the ‘Repairing Puppy-Bots’ spec.
As well, the smaller the problem space you set for yourself, the cleaner and more internally consistent your design will be. You start by, for example, designing the task resolution mechanic: roll 2d6 and sum them, or roll 8d6 and any fives and sixes are successes, or whatever. You don’t work through all its possible uses yet. You just imagine a single scenario: how do you pick a lock? How do you hit someone with an arrow? And then you design to just that scenario, just within that scope. When you’re done, your design will have minimal cruft and special cases and weirdness, because of how few distractions were present; the tightly-scoped spec is now a new building block you can use to construct other specs.
Object Oriented Design
Let’s go into a little more detail about object oriented design. The basic concept is that each element of a system should be envisioned as a self-contained ‘box’, with inputs and outputs. The innards of the box, what it does with the inputs and how it generates the outputs, is opaque to the rest of the system. The opacity is two-way, though: the innards of the box don’t know what’s outside it, either. The box knows only what comes in through its inputs.
There are a lot of advantages to this approach and I really don’t have the expertise or the space in this document to explore them all. But there’s a significant way in which this helps with spec-writing: it allows you to define the scope of the spec and then stick to that scope.
Start by figuring out what the inputs to your system are. Don’t try to figure out how those inputs are generated, or whether the part of the game that generates them has even been designed yet. Just identify what they are, and what kind of data you expect to come from them.
Then build the innards of your system’s ‘box’. What do you actually do with the information from the inputs? Let’s say I’m writing a spec about populating shops at a given planet. I expect to get information about the planet in the form of simple string tags. I want to know the population, the biome, the faction that controls it, how dangerous it is, and maybe one or two other descriptors that identify anything unique or interesting about the place.
Now, given just those tags, I need to figure out how we’ll build a shop’s contents. I can’t go back to the sim game for more details; it’s invisible to me. If it seems like I need more information, I should start by seeing if I can get it through my already established inputs; can I ask for another tag? If not, I can ask for more inputs, but the more inputs I have, the less self-contained the system becomes. In this case, I definitely want one more input: the player’s reputation status with all the factions.
Now I can build the system that makes a shop. I imagine a set of tables, each tied to one or more tags. I load up all the tables where all the tags match the tags I was given. I also imagine a set of faction-specific tables, with additional tags keyed to rep levels (neutral, friendly, allied, etc). I load only the faction-specific tables the player’s rep qualifies her for. I pick some items randomly off each table, and assemble them into a shop inventory. I pass the shop inventory back to the sim game.
There are certainly plenty of other pieces of data I could be grabbing and looking at. I could look at what you already own; I could look at what you’ve been buying lately; I could look at the results of specific missions; and so forth. But by paring my problem space down to just ‘tags + rep’ and ‘output a list of items’, I prevent myself from being distracted by extraneous possibilities. If one of those extraneous details turns out to be really super-important to someone, rest assured it will come up when your document is reviewed.
Specs Should Be Easy To Read
This is the second point from above. Specs should be easy to read and understand. There are a number of tools you can use to make that happen.
Use short paragraphs. If there’s any reasonable way to break the idea you’re writing in two, do it. Hit enter. Make a new paragraph. Each paragraph should contain only the words it needs to contain to express its idea completely. New idea? New paragraph.
Don’t digress. Ever. If it’s important, make a new section below the current one. If it’s not important enough to do that, don’t write it down.
Don’t use acronyms or abbreviations you haven’t personally defined, clearly, in an earlier part of the document. Don’t ever use more than one abbreviation in a single sentence.
Don’t write math out in text form. Google Docs has an equation editor; use it. Written math is useless and unreadable.
Always include examples. And when you include an example, be as complete and thorough as you can. Cover every step of whatever you’re demonstrating. Is there a random number generated during the example? Generate it, write it down, continue with the example. Is there a character? Name her. (I like Alice, Bob and Cathy.) Is there a Mech? Pick a Mech and use its actual stats.
Make a diagram if it will be clearer. Google Drawings is pretty easy to use to make a quick diagram, and it’s often the case that you can make a whole bunch of words go away with the right diagram.
Don’t be afraid of repetition. It’s fine to say something twice, if doing so makes your intent clearer. Elegance of rhetoric is a distant third to accuracy and clarity.
Specs are Not Bibles
There’s two parts to this tip. First, let’s address the moment where you are elbow-deep in spec and you just aren’t feeling it. Something about the design is crappy or unsatisfying or seems overly complex. You try to fix it but nothing seems to help.
It’s not the Bible. Cut everything that bothers you and start over. And by ‘cut’ I mean literally Ctrl-X and paste it somewhere else if you’re sad about losing it (you shouldn’t be) or you think you might need it (you won’t). Take the actual words out of your document, because they’ll lock you into a particular pattern of thought. Once the section of the spec (or hell, the whole spec) is empty, start again. Reorganize if you need to. Rename things. Give simpler examples.
In fact, sometimes it’s easiest just to… not even open the offending spec. You look at its name and think ‘yeah, that’s a shit design.’ Just delete it! Just delete it and start a new spec from scratch! Move it to a deprecated folder if you have to, but get the whole document, title and all, out of your working directory.
Second, let’s talk about the holiness of your spec. The text is just words, but the ideas behind the text are also not sacred. Your idea is not the one that will cure cancer and bring peace to the world. It’s just a piece of game design, probably a bad one. That is the mindset to be in: ‘this idea is probably not very good; I should get some more eyes on it and find out why it sucks.’
Assume your idea is wrong. Assume that other people around you are smarter than you (within their own specialties, of course) and when they see your idea, they’ll immediately see why it’s wrong. Assume they’re right. Then, using their feedback as a guide, try to see your idea through the lens of their perspective.
Sometimes this exercise convinces you that your idea really is pretty good after all; that’s fine. You arrived there honestly, not through the smugness that comes from finishing a particularly elegant piece of technical writing. You know it’s good because you assumed it was bad and then talked yourself into it.
More often, you learn that your idea has a flaw and that other person knew exactly what it was. You still have to fix it; you’re the designer, you solve the design problems. But now you know where the problem is.
Importantly: don’t let on that you’re assuming your idea sucks. If you do that, you just encourage people to be nicer because they think you feel bad and want to cheer you up. You don’t need to be cheered up; you need to identify design problems and solve them. Resist the urge to be falsely modest or self-deprecating out loud. Just keep firmly locked away in your mind, while discussing: my idea sucks, and this person probably knows how to fix it.
Specs Must Be Honest
You’re writing a spec and you’ve got this cool system for progression. You’ve got a spreadsheet and graph that show how nice and clean the progression is, a really cool curve that you’re super-proud of. There’s just one problem: at the low end of the progression curve, the whole system falls apart. It just stops working.
But it would take a lot of math for someone to realize that. They’d have to run simulations, or do some theorycrafting, or whatever. They probably won’t if they’re not prompted to do so. If you just don’t mention the flaw, nobody will know and your awesome system will get implemented.
This is bad. This is not hypothetical: it’s called the Savage Worlds system, it powers a variety of tabletop RPGs, and there’s an obvious flaw at its low end that isn’t mentioned or fixed anywhere in the text, even though the designers clearly knew the flaw existed.
The game doesn’t care how convinced other people were at the brilliance of your idea. It doesn’t care that the engineers had no idea the flaw existed. The game is a set of mechanics. Your job is to understand those mechanics and ensure they all work properly. If they don’t, your rhetorical skill is useless, because you’re shipping a game, not a spec, and flaws will be found and exploited.
Anticipate Questions and Comments
If you’re writing something and you can almost hear someone reacting to what you’re writing, stop and consider how to address their reaction now, saving both of you time in the ensuing meeting.
Don’t try to avoid the question in any way other than answering it. Distractions, attempting to subvert the question in advance, red herrings to make the question hard to answer; none of these are okay. If you think of a legitimate question for your design, interrogate yourself first, and if you can’t answer it or reconcile it, rethink that part of your design.
You Are Not An Engineer
Don’t try to construct the underlying architecture of a system. Don’t write pseudocode, ever. Don’t make assumptions about the way the data will be structured, or how it will be retrieved.
The best way to approach the interface between design and engineering is to treat the engineering side as a black box. You tell the box what you’d like to have happen, and assume the box will provide that.
For example, let’s say you want to be able to figure out how much a Mech costs to build. You don’t know how the Mech is defined in data, but you know it’s made out of a chassis, weapons, and components. Your approach should be something like this:
“Sum the C-Bill cost of all the components and weapons in the mech, and add the total to the C-Bill cost of the chassis. The resulting value is the total mech cost.”
There are a few things going on in that design snippet, so I want to look at each of them.
First, I don’t know how the engineers are tracking costs of anything, so I don’t make any suppositions. This snippet tells the engineers that if they don’t currently have the ability to sum all the component costs for a single Mech, they need to add that functionality, because we need to use it.
Second, notice that I call out ‘C-Bill cost’. I don’t have any other costs in mind at the moment, but the point is that I could, and it’s less ambiguous to say ‘C-Bill cost’ every place that ‘c-bill cost’ is actually what I mean. The time saved by not typing ‘c-bill’ is not worth any additional ambiguity or confusion later on.
Third, I refer to ‘components and weapons’ as two separate items. This is because I can imagine wanting to sum only the cost of weapons, or only the cost of non-weapons. I know that technically ‘components’ includes the weapons, but if I don’t put the word ‘weapons’ in there, I know that someone will say to me: ‘Does this include the weapons?’ So I’m anticipating that question and i’ve answered it ahead of time.
Fourth, I break the math into two distinct steps. I do this so that there’s no confusion due to placement of commas, conjunctions, or whatever. There are two clear steps: sum and then add the total.
Fifth, I give the results a specific name (‘total mech cost’) and I italicize it. I also call it ‘the resulting value’ as opposed to ‘the result’ or ‘the value’. I’m juggling a lot of results and values in the previous sentence; best to be entirely clear.
The overall result is that an engineer, reading that snippet, knows exactly what code to write. Not because I’ve told him how to do his job, but because I’ve given him comprehensive information about what I’m trying to get the game to do.
Organize Your Thoughts
Start with an overview. This should summarize the entire design in a few sentences. I like to structure it as ‘Here’s the objective. Here’s how we’ll accomplish it. Here’s some details on that.’ The overview should make it completely clear what designs are contained within the document. If there’s a sneaky extra section at the bottom that covers something only tangentially related to the spec’s topic, the overview’s a good place to realize it doesn’t belong, and should be moved to another spec or to its own document entirely.
Use headers to divide your document into logical sections. Each section should essentially stand alone as a complete addressing of its topic. This should propagate fractally down through the document; each time you break a section into sub-sections, each sub-section should be relatively standalone. Headers also allow Google Docs to build a table of contents automatically.
Make sure that you write in order from broadest to most specific, and from foundations to specific cases. For instance, a spec about structures might start with what structures are, progress to defining each part of a structure (art, damage states, hit points, taking damage). Weapons are a larger issue, so we break those out into another section. Then we get specific again, talking about firing arcs, ammo, and heat. Finally we move to the very, very specific: some examples of how we’d express common map features as structures: turrets, repair bays, hangars, bridges.
Don’t promise to define something later in the document. If you haven’t already defined it, you need to reorder your sections. No concept should be used before it’s defined, and if you end up with some kind of strange looping definition, you need to either break down your sections and reassemble them, or you need to consider what kind of shenanigans you’re up to that your design is that complicated.
