Writing it down

A decision that lives only in a meeting is a decision that will be remade, usually by someone who wasn't there. Writing is how an FDE scales beyond the conversations they can attend. This chapter covers the few documents that matter, and how to make each one usable by a stranger.

Three documents carry an engagement#

Each is written for a different reader at a different moment. The brief is for the sponsor, early, to confirm you understood. The design doc is for technical owners and reviewers, before building. The spec is for whoever builds and tests, including people who will never meet you.

The problem brief#

Write it after two or three discovery conversations, send it to the sponsor and champion, and ask them to correct it. Disagreement at this stage is cheap and valuable. A brief that comes back with edits is working.

• Problem statement. One or two sentences that the sponsor and the people doing the work would both sign.
• Baseline. What it costs today in hours, money, errors, delay or risk. Use their numbers.
• Success measure. The number that will tell the sponsor it worked, and the target.
• Decision-makers. Who approves the solution, who can veto it, and who has to live with it.
• Constraints. Deadlines and why they exist, data that is off limits, systems that can't change, required accuracy.
• Open questions. What you still don't know, and who can answer it.

Criteria a stranger can test#

An acceptance criterion is the line that says when one piece of work is finished. Judge it with the stranger test: hand it to a tester who has never met you. If they can write the test without messaging you, it's done. If they would need to ask "which case?", "how fast?" or "what should I see?", it isn't.

Dan North's Given / When / Then format, from behaviour-driven development, is a reliable way to pass the stranger test. Given says where things stand before anything happens. When names the single event. Then says what anyone could check afterwards. Add a number wherever time, size or quantity matters.

Three smells tell you a criterion will fail the stranger test:

• Adjectives. "Quick", "intuitive" and "robust" are opinions. Replace each with something a tester can see or measure.
• Bundles. One sentence covering the normal path, the limits and the failure. Split it, so each outcome gets its own criterion.
• Negatives. "Bookings must never be lost" can't be checked. Say what happens instead: "an unsent booking is kept as a draft and reopened on the next visit".

Edge cases you can finish listing#

"What could go wrong?" has no end. A short, fixed set of questions does. Ask each of them of every criterion, and write the expected behaviour for those that apply. They are standard categories from software testing.

The "twice" case has a well-known engineering answer. The client attaches a unique key to the request; the server recognises a repeated key and hands back the original result instead of acting again. Payment companies call it an idempotency key. The spec doesn't have to design that mechanism, only promise its effect: one booking, however many times the button is pressed.

Then prune. Keep a case if getting it wrong could hurt someone, cost money or breach a rule; if it will happen in ordinary use; or if two engineers would plausibly handle it differently. A long list of unlikely cases buries the few that matter.

AI features need two specs#

When ordinary code fails it usually throws an error someone can catch. When a model fails it usually returns something that looks fine. So an AI feature needs a second spec beside the first: not only what a good result is, but what the person in front of the screen sees at the moments when there isn't one.

Google's People + AI Guidebook has a chapter on errors and graceful failure worth reading before you write this section. Give each behaviour an owner: several are product or policy decisions, not engineering ones.

Specify the good answer, and specify what happens when there isn't one.

Decisions with an owner and a date#

Reviews tend to end with a pile of comments and no decisions. Prevent that with a small table near the top of the document: the questions that need settling, who settles each one, and by when. Reviewers told exactly what they own reply faster than reviewers asked for "any thoughts".

Bain's RAPID model is a good check on that table: for each decision, someone recommends, some must agree, some give input, someone does the work, and exactly one person decides. If the "decides" column holds two names, the decision will stall.

When requirements arrive late

New requirements always turn up just before a build starts. Accepting every one wrecks the date; refusing them all wrecks the relationship. Sort each into one of three piles, and note the result in the change log.

• In: the release can't meet its goal without it, and you know what it costs. Update the criteria and get them signed again.
• Later: worth doing, not needed for this goal. Into the backlog with a one-line reason.
• Up the chain: it changes the goal, the date or the budget. That is a sponsor's call, not yours.