Why specs go unread, and who actually reads them

A spec is any document that tells a team what to build and why. The most common kind is a PRD, a product requirements document. Most unread specs fail in the same few ways:

• They are written to win approval, so they argue instead of deciding.
• The first decision appears on page six.
• Problem and solution are mixed, so nobody can tell which parts are fixed and which are open.
• They use words that mean different things to different people: fast, simple, real-time, all, intuitive.
• They go stale in week two, so people stop trusting them and ask in chat instead.

The fix starts with the readers. A spec has several, and each one arrives with a different question and a different amount of patience.

Since readers stop at different depths, put the most decision-heavy content at the top. Journalists call this the inverted pyramid. The first five lines of your spec should let a sponsor approve or reject it without reading further, and every later section should add detail without changing what the top says.

Working backwards: the PR/FAQ

Amazon's best-known planning habit is to write the launch announcement before building anything. Colin Bryar and Bill Carr describe it in Working Backwards (2021): the team writes a PR/FAQ, a press release dated on the imagined launch day, followed by frequently asked questions. The press release is short. The FAQ covers the customer experience and the cost and difficulty of building it, and they say it should be five pages or less. Teams often go through ten or more drafts. In the review meeting, everyone reads the document in silence first, and the most senior people speak last so they do not steer the others.

A press release has a fixed shape, and each part tests something:

• Headline: who gets what benefit. If you cannot write it in one line, the benefit is not clear yet.
• Summary paragraph: what launched, for whom, and the main benefit.
• Problem paragraph: the pain today, in the customer's words and numbers.
• Solution paragraph: how it works from the customer's side. No architecture.
• Leader quote: why the company did this. It tests whether the idea fits the strategy.
• How to start: the first step for a customer. It tests whether adoption is realistic.
• Customer quote: what you hope a user will say. Base it on words you heard in interviews (User interviews that don't lie), so it stays honest.

The FAQ has two halves. External questions are what customers will ask: what does it cost me, what if I have no signal, what if the driver has already left. Internal questions are what leaders will ask: why now, what does it cost to build and run, what must be true for this to work, what are the biggest risks, what are we not doing, how will we know it worked. Put the hardest questions first. An FAQ that dodges the cost question is a sales pitch.

The method works because a vague benefit cannot hide in a press release. "Improves efficiency" reads as empty the moment you put it in a headline, so the team is pushed to find the real benefit or drop the idea, and dropping it costs a few days of writing instead of months of building.

For internal tools, the "press release" is the message the head of operations would send to every store manager on launch day, or the voice note a sales rep would play to shop owners. If you cannot write a message that makes Ama, the store manager, say "finally", rethink the feature before anyone draws a screen.

The one-page PRD

Once the PR/FAQ is approved, write the PRD the team will work from. Keep its core to one page, roughly 500 to 800 words, and link out to research, designs and the story list. Long PRDs feel thorough, but the extra pages are usually screens and wishes that belong in the design file and the backlog.

A one-page PRD has these parts, in this order:

1. Summary: the problem, the outcome you want, and what you are asking for.
2. Problem and evidence: numbers, two or three quotes, a link to the research.
3. Users and context: who, where, on what device, under what pressure.
4. Goals and guardrails: outcome metrics with a baseline, a target and a date; one or two guardrail metrics.
5. Non-goals: what is deliberately out, with the reason.
6. Solution outline: the shape of the solution in a few sentences, plus links to designs.
7. Requirements: a prioritised list that points to the user stories (User stories and acceptance criteria), plus the non-functional requirements.
8. Risks and assumptions: what must be true, and how you will check it.
9. Open questions: each with an owner and a due date.
10. Launch and measurement: pilot, waves, and the date of the post-launch review (Launching).
11. Decision log: every decision taken after approval, with the date and who decided.

Other good formats use different names for the same ideas. Google's design docs, as Malte Ubl described them in 2020, start with context and scope, then goals and non-goals. Basecamp's Shape Up (Ryan Singer, 2019) asks for a "pitch" with five ingredients: problem, appetite, solution, rabbit holes and no-gos. All of them say what you are solving, how much it is worth to you, roughly how, where the traps are, and what is out.

Goals, non-goals and open questions that do real work

Goals describe a change in the world, measured. Each one needs a metric, a baseline, a target and a date, plus where the number comes from. Write them so that at the post-launch review anyone can say "hit" or "missed" without arguing about what the goal meant.

• Weak: "Improve the claims experience for partner shops."
• Strong: "Median time from delivery to credit note falls from 9 days to 2 days by 31 March, measured in the finance system. Guardrail: credit notes stay below 1.5% of delivered value."

Non-goals are things a reasonable person could expect the project to do, which you have decided it will not do. Google's design-doc guide puts it the same way: things that could reasonably be goals but are explicitly chosen not to be. "The app will not crash" is a negated goal and adds nothing. "No cash or wallet refunds in this release; claims are paid as credit against the next invoice, because refunds need a separate finance approval process" is a real non-goal. It stops a stakeholder from assuming refunds are coming, and it stops a vendor from building them.

Open questions are the uncertainties you know about. Each one gets an owner, a due date and a note on what depends on it. "Can shops claim after the driver has left? Owner: head of DC operations. Due: 14 Nov. Blocks: the late-claim story only." A question without an owner is a hope. Linking each question to the stories it blocks lets the rest of the work start.

Finally, hunt for the slippery words. Replace "fast" with a time on a named device, "all" with a list, "real-time" with a delay ("within 60 seconds of the driver confirming"), and "easy" with a task and a time ("a first-time user can file a claim in under a minute"). Every slippery word left in a spec turns into an argument later, and with a vendor it can turn into a bill.

Review, decide, keep it alive

Run the review like Amazon's: start the meeting with 10 to 15 minutes of silent reading, collect comments in the document, then discuss. Silent reading means everyone argues about the same text, and quieter people have time to form a view. End with one of four outcomes: approve, approve with named changes, rewrite, or stop. Write the outcome in the decision log before people leave the room.

After approval the spec becomes a living document. Keep a status line at the top (Draft, In review, Approved, Building, Live), a version, an owner and a last-updated date. When a decision changes, update the decision log, the affected stories and the people who rely on them, in that order. Keep one copy: the tracker links to the spec and the spec links to the tracker (Planning on GitHub shows one way to wire this).

If an outside company builds the feature, the approved PRD and its stories are often attached to the statement of work. From that moment, a change to the spec is also a change to a contract and usually needs a change request (Working with vendors and agencies). That is one more reason to resolve open questions before signing.