Have I repeated my Prime Directive enough? ;-)

Making specification documents effective

Practical advice and samples

Have I repeated my Prime Directive enough? ;-)



This is a detailed follow-on to my post about how the purpose of a specification is to communicate. Let's call that my Prime Directive of spec writing. That post laid out the broad strokes of a format I settled on (which will naturally continue to evolve). Here, I'll cover "my" format in detail. I put quotes around "my" because naturally none of this is pure invention—I rolled up ideas from many sources into a system that worked for me and my team.

As I go through these details, I'll use the creation from scratch of a simple CMS as a token example. I'll also provide links to starter docs.

How to work your lattice

As I said in the specification artifact overview, to keep specs digestible, you'll wind up with an entire library of them. These form a latticework that together will describe your product comprehensively (or nearly so). So how do you know how to break down an effort into multiple documents instead of one? Finding the proper "chunk size" is more of an art than a science. Your guideline should always be what helps me communicate?, with the added qualifier of is it digestible?

Sometimes it's fairly obvious—if you've got a well-defined project or module, like bolting comments onto articles in an existing CMS, that's probably a single spec (even if it's an "epic" in agile terms). In my example, we're dealing with total greenfield development, and it would not be easy to digest everything from post creation, display, scheduling, tagging, sharing, landing pages, and comments in a single document.

Document or spreadsheet?

I encourage you to use online documents that support versioning as well as collaboration features—team editing, comments, e-mail notifications on new comments/replies, etc. A key stylistic decision to make is whether to use a word processor document ("tall" spec) or a spreadsheet ("wide" spec). This depends partly on your tolerance for side-scrolling: use cases need a lot of columns in a spreadsheet presentation.

As you read this, please refer to my examples (and feel free to use them as the basis of your own format!):

One advantage of the word-processor style (hereafter referred to simply as "documents") is that they support internal links and tables of contents, which can be super-helpful in longer specs. And, if your spec consumers are going to be printing them frequently (hopefully not), a hard copy of a document will be much more readable than a printed spreadsheet.

Image-rich specs with visuals like wireframes and comps present a special case that I may cover in another post, and each format has pros and cons. You may want to consider different kinds of artifact altogether for these—PDFs, images, Balsamiq files, whatever.

The big advantage of a spreadsheet is that adding a column to all your use cases (for example) couldn't be easier. Adding the equivalent (a new field) to each use case in the document format is tedious at best, and the more use cases you have, the worse it gets. You can make up your own hypothetical, but maybe after the first go-around your engineers want to capture estimated difficulty level in a new field. One solution is simply to add such new content to the "Notes" box, which I suppose isn't as rigorous, but works just fine for avoiding the retrofit of an existing spec.

As you can see, like so many things in PdM, there's no right answer and many trade-offs between the alternatives. The smart course is to pick a format, live with it a bit, and if the bad outweighs the good, switch to the other or come up with something else new. Finding your approach is an iterative process. Let continuous improvement trump precedent—but realize that if your spec format changes constantly, it will confound your consumers. (Sounds kinda like a user experience design problem, doesn't it? That's because it is.)

Tools change the work

Just an aside about why I think it's worth putting a lot of care into building your format: the tool you use subtly changes how you work, even how you think. Since one of the objectives of the specification process is to give tactical PdMs the space to thoroughly work out details of a feature, the way your tools simplify or complicate that process is important. For instance, that thought process is meaningfully different if you're stating requirements in the form "The CMS shall support post tagging" as opposed to the user story equivalent: "As an author I want to tag posts so that we can create topic landing pages that improve SEO". (I think user stories are clearly superior, by the way.)

My format

My format for specifications has three main parts: a preamble followed by user stories that, to use a programming term, decompose into use cases.


Apart from being a place to record revision history, links to related specifications, and other housekeeping, the preamble should summarize the featureset as well as the business case for creating it. If you've created an MRD, this summary will overlap it. In any case, I believe it's very important to package the functional requirements together with their business justification. The benefit of this approach to non-technical stakeholders is obvious, but even engineers need to understand the why behind the what. Besides, it's a fantastic way to head off objections over how "dumb" something is. Engineers are good at computering, which makes some of them forget that not everyone is. Justifying features and workflows in advance not only prevents grousing, it also forces you to think things through, which is hugely beneficial.

User stories & use cases

A detailed discussion of user stories and use cases is out of scope, but here are the basics.

User stories should be scannable sentences that identify an actor (kind of user), what the actor wants to accomplish, and the business value derived from that action. As such, they contain no details of workflow or interface. Taken together, your user stories will completely describe the module or featureset in a way that is easily digested.

Here's an excerpt from my fictional CMS:

ID As a… …I wanna… …so that I can…
MyCMS.us1 Reader view a paginated list of posts navigate to some content I'm interested in
MyCMS.us2 Reader view a post be edified and amazed by relevant-if-verbose writing

Use cases are the detailed requirements for the engineers. Here is where you capture the entire workflow, including exceptions and outcomes. Use cases derive from the user stories, though there won't always be a 1:1 mapping of the two: a single story might require several use cases, and/or a single use case might satisfy multiple user stories. Also, you may find that the actors on use cases are different than a corresponding user story. This is not cause for concern as long as it makes sense to your readers.

Here's an example of the "tall" (non-spreadsheet) variety:

MyCMS.uc1: Post display [Must]

Story (-ies) MyCMS.us2
Description A page that displays an individual post.
Actor(s) Reader, System
Preconditions A post with an identifier matching the key portion of the URL exists.
Main flow

1. Reader requests page with a given URL.

2. System parses the search engine friendly (SEF) blog title portion of the URL to use as the post ID.

3. System retrieves the post content.

4. System retrieves user-assigned tags for the post.

5. If tags are found:

—5.1 For each tag, system presents each, wrapped in a link that leads to the post list page filtered by that tag.

6. Else (no tags), skip the tags section of the page.

7. System injects the content and formatted tags into the base blog post template and returns it to the user agent.

Postconditions Reader is able to read the post, and navigate to a tag-filtered list of other posts.
Alternate flow(s) If no post matching the SEF identifier exists, system redirects the user to our über-clever 404 page.
Notes See the visual spec to get an idea of how the injected content will look in the base template.

Note the "[MUST]" is a MoSCoW classifier (see below). Tip: In a document, make that whole line identifying the use case a heading of some level; that way, use cases and their priorities will be included in the table of contents, which can be scanned quickly in the same way that the spreadsheet variety allows.

Lots of quibbles can arise when we look at use cases in detail. How should if/else steps be numbered? How about loops? Is what I'm calling an alternate flow really that, or should it be captured as a branch in the main flow? (More importantly, are the steps crossing over the line from functional requirements into implementation details? Arguably, these have.)

Take this as a token example, not an ideal one. But don't obsess over them either—if you follow the Prime Directive and your writing clearly communicates the intent, you can rely on smart engineers to implement them appropriately. The numbers are there mainly to let you quickly refer to specifics in other communication: "Hey Dave, I think you missed step 3 in MyCMS.uc11."

Other parts

The three main sections will appear in every spec, but you're certainly not limited to just those. Consider a specification for some kind of API, in this case, a web bug (a.k.a. beacon or tag) similar to those used by Google Analytics and similar systems. You'll need a list of each field accepted on the beacon call, the data type (integer/string/whatever), whether it's required or optional, etc. The body of a use case is not the most convenient place for this kind of nitty-gritty. Instead, create a separate tab in your spreadsheet or section in your document.

You should also record key decisions in a separate section. Specs are living documents (especially during development), and as the details evolve, it's good to have a summary of when and why important decisions landed the way they did. (In the spreadsheet variety, you can have this in its own tab or on the preamble tab.)

More tips

Codenames—useful but dangerous. Giving each effort (spec) a concise codename is helpful and even fun. (I'm infamous for coming up with names like Ginsu, DiscoFerret, ContentVampire, PDQ… the list goes on). The concern here is that customer-facing folks can get stuck on the codewords—it's probably not smart for sales or customer success to refer to a system that pulls ingests text from one system into another as a "vampire". Have some personality (fitting the culture of your workplace), but choose codenames wisely; even then, product managers and product marketers can expect to spend some time drilling the public-facing name of a feature into the minds of many stakeholders.

Avoid overly generic actors. If you find that your user stories repeat the same actor frequently, or that the actors are too generic, spend some time thinking through the stories. Are they granular enough? Meaningful enough? Can some of them be rolled together without losing fidelity?

Avoid excessive branching. Too many if/elses in the main flow of a use case muddies the concept (and simply makes it harder to type them out). Use the alternative flows field to capture exceptions

It's a spec, not a religion. Don't worry overmuch about deviating from convention. If you find that the description field on a use case is overkill or that you don't care to capture priority within the spec itself, cut those fields out.

Don't waste time on the obvious. For instance, if every alternative flow says "the system shall present a 'try again' message if the database server is temporarily unavailable", capture that detail somewhere else.

MoSCoW: "MoSCoW" lets you group parts of an epic into general must/should/could/won't buckets ("Won't" is there to indicate that you considered something and discarded it, but may revive it in a later phase). You'll see these indicators in my examples. Work will proceed according to a stack-ranked list rather than buckets (especially in agile environments), but you may find as I did that MoSCoW helps implicitly capture phases/sprints. If not, just skip it.

Don't forget the core purpose

One last pair of tips… rely on the Prime Directive—that the purpose of a specification is to communicate—as the basis for every decision about both format and content. Cut out that which impairs communication; add that which improves it. But within that, keep your own tedium to a minimum. As with everything in software (life?), you'll reach a point of diminishing returns, and once you do, be judicious about whether any additional investment will pay off.


What specification formats have you used, and how did they work out for you? Do you use the as-a-someone-I-want-to… format for user stories? Something else? Any other tips or debate? Let us know in the comments below.