They're like blueprints, but easier

How to write specifications: artifact overview


They're like blueprints, but easier



There are many ways to specify software, and no one way is right or wrong. However, I can lay out one absolute truth: the purpose of a specification is to communicate. Case closed. That's it for the philosophy.

Of course, that kind of bold-faced claim is at risk of being an empty non-statement, so let me explain: you can treat it as a kind-of Occam's razor to evaluate every step you take in spec writing. If you're devising a new specification format (or evolving an existing one), make sure each alteration improves your ability to communicate efficiently. When writing specs, apply the same scrutiny to each detail packed into workflow descriptions. If what you're doing doesn't advance the purpose of communication, do something different.

This article is intended as a recommendation for junior PdMs, food for thought for experienced ones, and a suggestion for startups who are looking to "professionalize" their specs. This is about artifacts, so I'll save things like requirements discovery and UX design for a later post—and I encourage you to investigate all these other good resources covering the specification process.

Your goals and audiences

Within the overall purpose of communication, there are two main objectives: describe the software (duh) and elicit creative feedback. (A third objective is to give the PdMs an opportunity to think things through.) Regarding feedback, it is essential to have your assumptions challenged. Not even a Jobsian visionary defines software in the absence of collaboration. This is why I prefer web-based tools that support comment streams, ideally one with e-mail notifications for new comments and replies.

The primary audience for any specification is your engineering and QA teams. (If it's not, you're probably writing an MRD or something of that ilk.) The secondary audience is pretty much every other internal stakeholder. Both audiences need the spec documents to satisfy both main objectives, but in different ways, as I describe below.

In any shop that is or has aspirations to be agile, specs will be a living document, changing frequently during the development phase. Importantly, they are also a historical document. Downstream consumers like support teams should be able refer to them as long as a given feature is still in use. (This even applies to you-from-the-future—y'know, because you can't step twice into the same river.) This implies that specs need to be maintained even after the feature set is no longer actively being worked on, or that they become useless as historical artifacts pretty quickly. I much prefer the former, but it is a non-trivial investment, and the PdM organization needs to be rational about when the point of diminishing returns is reached. Fortunately, lightweight spec formats are easily maintained even over the long haul.

My format in a nutshell

The purpose of a specification is to communicate, not to be the worldly embodiment of an ideal form. I am not a ceremonialist, and I think once you've found a format that gracefully satisfies your communication aims, you're good to go. That said, some formats are more conducive to the three objectives I laid out than others. Agile formats are in vogue for very good reasons, but if PRDs and FRDs are best for your organization, by all means, use 'em.

My article Making Specification Documents Effective covers the format I landed on in detail (with samples you can use), but in broad strokes here is what I found to work well:

  • A preamble: the elevator pitch for your feature set—a succinct description of the feature, its overall motivation, and some market justification. This is also the place for housekeeping items like revision history and links to related specs.
  • User stories: a list of various user archetypes and what they care to achieve, in the format "as a [user type] I want to [whatever] so that I can [some business objective]". Example: system administration software might have a story that says "as a sys admin, I want to set rules on password complexity so that I can ensure the security of workstations and networks." (Or maybe they just want to satisfy this xkcd classic.)
  • Use cases: functional details that elaborate user stories into actual step-by-step workflows that engineers will use to build and test the software.

If you're building something UI-heavy, you'll want to accompany these with pretty pictures (or at least wireframes), and you should absolutely not waste hundreds of words when a picture with callouts would clearly communicate your intent.

Mapping audiences and section

Your various audiences will use these three main written sections in different ways:

  • Dev & QA will of course be using the whole thing.
  • Sales, biz dev & marketing need to understand what is planned and what general user problem it intends to solve, so that they can prepare their various pitches and assets; for this, they'll rely heavily on the preamble and user stories.
  • Tech support will mostly use specifications as historical documents, and they will refer to the detailed user workflows in the use cases.
  • Customer success teams (engagement managers, account directors who own long-term customer relationships, etc.) will also often use these as historical records to understand part of the product they may not have touched in some time.
  • Management: your GM, the board, investors, potential acquirers—to a varying degree, these folks will want to know the details of your ambitions, but they all want to know that you've thought things through, and a good spec document will make that clear.

One spec per epic

Anything beyond the simplest product should be specified with a latticework of documents, each describing one coherent feature set. In agile terms, this is an epic, though not all epics are created equal. Keep in mind that reasonably small documents are consumable; too small and they are cards or tickets, not specs; too large and they're difficult to navigate or even grasp. How do you know when you've hit the sweet spot of effectiveness without waste? Practice, I suppose. Finding that break-even point is an art, not a science.

(Using heavy-duty requirements management software would negate this latticework approach, or maybe just encapsulate it differently since the tool itself lets the user navigate a product's monolithic spec as if it were in different documents. But, I've never been in a situation where I could justify the expense of a heavy RMS.)


What specification formats have you used, and how did they work out for you? Have a favorite tool? A most-hated practice? Comments are below—communicate!