Writing the spec

Discovery ends with a decision and some evidence. Delivery needs something more precise: a description of what will be built that a designer, an engineer and a tester can all work from. That is the job of the spec. It is also the job most often done in a hurry.

Start with the goal, not the solution

The first section should say what problem is being solved and how you will know it has been solved. If discovery went well, this is mostly copying: the outcome, the opportunity you chose, and the key evidence behind the decision. One or two short paragraphs.

Opening with the solution instead — “we will add a CSV export to the reports page” — tells the reader what to build but not why, so every later trade-off has to be guessed. A sentence of context lets people make sensible decisions you did not anticipate.

Draw the boundary

Scope says what is in and, just as importantly, what is out. The out-of-scope list is the most underrated part of any spec. It costs a few lines and saves weeks.

Be specific: “the export works in desktop browsers; on phones the button is hidden” is far more useful than “mobile is out of scope”. It also helps to list what is deferred rather than rejected. Writing “scheduled exports — later, once we see how manual export is used” shows the idea was heard, which tends to end the discussion faster than silence does.

Requirements someone could disagree with

The test of a good requirement is that someone could reasonably object to it. “The export should be fast and easy to use” constrains nothing. “An export of up to 10,000 rows completes within five seconds” can be argued with, measured and, if needed, changed.

• Number them. “R4 conflicts with R7” is a much better review comment than a paragraph of explanation.
• Name the role. “Users can…” is vague when there are admins, members and guests.
• Separate must from nice-to-have. If everything is mandatory, the team will set its own priorities.
• Leave design open where it does not matter. Describe the need, not the widget.

Non-functional requirements — performance, accessibility, security, data retention — belong here too. They are the ones most often left out and the most expensive to add later.

Acceptance criteria that can be checked

Acceptance criteria turn requirements into observations: given a situation, when something happens, then something specific is true. Their job is to let someone decide, without asking the author, whether the work is finished.

Most weak criteria fail because they describe a feeling rather than an observation:

Good criteria also cover the edges — empty reports, very large ones, users without permission — and sometimes say what must not happen. A quick test for any criterion: could two people check it independently and reach the same verdict? If not, it needs another pass.

Open questions and decisions

End with two short lists. Open questions, each with a person responsible for answering it: a question without a name next to it tends to stay open until someone trips over it in testing. And a dated log of decisions, added as they are made rather than by quietly rewriting earlier sections.

A plain outline

# [Feature name]
Status: Draft | In review | Agreed | Superseded
Owner: [name]   Last updated: [date]

1. Goal        problem, outcome, key evidence
2. Scope       in / out / deferred
3. Requirements
   R1. [Role] can [action] so that [result]
   N1. [non-functional]
4. Acceptance criteria (per requirement)
5. Open questions  [question / who / by when]
6. Decisions       [date / what / why]
Appendix: research, data, alternatives

Keep it short enough to be read

A spec nobody reads in full is worse than a short one, because people skim, assume and then quote the parts that suit them. For most features, two or three pages is plenty. Put background and rejected alternatives in an appendix or a linked document.

Once the spec is agreed, the next step is deciding how to build it in pieces: Slicing the work.