How to write a product spec that engineers actually read

By Meet Patel · 2026-10-03 · 6 min read

In the first part of his 2000 essay series on functional specifications, Joel Spolsky sets two hypothetical programmers the same task. Speedy starts coding immediately and finishes in four weeks with code he later wishes he had designed differently. Mr. Rogers writes a spec first and finishes in three weeks with a better architecture. The numbers are Spolsky's illustration, but the mechanism is real: rewriting a paragraph takes minutes, and rewriting a module takes days.

A product spec that engineers read is one to two pages long. It opens with the problem and the evidence for it, states what is out of scope, defines acceptance as testable statements, says how success will be measured, and lists open questions with owners and dates. The rest of this post walks through those parts in order, gives a worked example, and ends with a way to review the spec before anyone builds from it.

What a spec is for

Spolsky gives four reasons to write one. The act of describing the program in detail forces you to design it. A written spec saves answering the same question repeatedly for QA, technical writers, marketing and support. It makes scheduling possible, since he argues that without a detailed spec it is impossible to make a schedule. And it forces design arguments to resolve before they are buried in code.

These four reasons tell you what to include. Every section should answer a question that someone would otherwise ask an engineer in a chat thread. If a section answers nothing, delete it, because a long document with a dead section teaches readers to skim.

Step 1: state the problem and attach the evidence

Two to four sentences on who has the problem, in what situation, and what they do today. Then the evidence: ticket counts, interview notes, funnel figures, each with a date and a source. A spec without evidence asks engineers to trust a preference, and engineers are right to be cautious about that.

If you have written the situation as a job statement, paste it here. The post on writing the job before the feature covers that format.

Step 2: set one goal and one measure

One sentence for the goal and one metric for the measure, with the current baseline, the target and the date the result will be reviewed. Several metrics invite a team to claim success on whichever one moved. If you have no baseline, the first deliverable of the project is measuring it.

Step 3: write the non-goals

Spolsky's second article lists the parts of a spec and is blunt about this one: “You have to start culling features right away, and the best way to do this is with a 'nongoals' section.” A spec that only states what is in scope has no defence against the requests that arrive in week two.

Good non-goals are things a reasonable person might expect to be included. “Does not support mobile” is useful if mobile users exist. “Does not cure cancer” is not. Each non-goal can carry a one-line reason, which is also the place to record what would change the decision. The PM's veto makes the wider case for saying no to features, and the non-goals section is where that no gets written down.

Step 4: describe the behavior and write acceptance criteria

Describe the behavior in the order the user experiences it, including the empty state and the failure cases. Spolsky recommends realistic scenarios, with a stereotypical user in a specific situation, as the way to keep the description concrete.

Then write acceptance criteria as statements a tester could pass or fail. A common format is Given, When, Then: “Given a saved filter exists, when the user opens the orders table, then the filter is applied and the row count matches it.” Replace adjectives with thresholds. “The page loads quickly” cannot be tested, whereas “the filtered table renders within two seconds for 10,000 rows” can.

Step 5: specify the instrumentation

List the events to record, the properties each carries, who reads the result and on what date. This step is the easiest to leave out, and without it the goal from Step 2 cannot be measured after launch. The definition of the metric belongs here too. I have written about how onboarding completion gets mistaken for real activation in your activation metric is a lie, which is what happens when a definition is never pinned down.

Step 6: list open questions with owners

Spolsky calls this section Open Issues and advises resolving all of them before programmers start coding. I would add that each question needs a named owner and a date. “Pricing tier TBD” sits there for months. “Owner: pricing lead, answer by the 14th, blocks the billing work” gets answered.

Five mistakes that make engineers stop reading

• Solution first. A spec that opens with a screen mock-up makes the problem look settled, and engineers who see a better route have no way to propose it.
• Adjectives for acceptance. “Intuitive,” “fast” and “seamless” cannot fail a test, so they cannot pass one.
• Questions buried in prose. An uncertainty written as an assumption (“we will use the existing permissions model”) becomes a decision nobody made.
• Written by committee. Spolsky's list gives a spec a single author, for accountability. Reviewers comment, and one person decides what the document says.
• Never updated. When behavior changes mid-build, change the spec the same day. Otherwise QA and support will trust a document that is wrong.

A template, with a caution

In his fourth article, Spolsky advises against a standard spec template, because templates accumulate sections nobody needs and discourage people from writing specs at all. That is a fair risk, so treat the following as six questions the spec must answer, and delete any heading whose honest answer is “nothing.”

1. Problem and evidence: who, in what situation, what they do today, and the dated evidence.
2. Goal and measure: one sentence, one metric, baseline, target, review date.
3. Non-goals: what a reasonable person might expect and will not get, with a reason.
4. Behavior and acceptance criteria: the flow in order, plus pass-or-fail statements.
5. Instrumentation: events, properties, reader, date.
6. Open questions: each with an owner, a date and what it blocks.

A worked example (hypothetical)

Take a 20-person SaaS company adding saved filters to an orders table. The filled-in spec fits on one page.

• Problem and evidence: account managers re-apply the same three filters every morning. Illustratively, 31 support tickets last quarter mention it, and two customers named it in renewal calls.
• Goal and measure: reduce time to reach the daily orders view. Baseline 45 seconds by observation of five users, target under 10 seconds, review 30 days after launch.
• Non-goals: sharing filters between users (a larger permissions question), filters on the mobile app, and scheduled exports.
• Acceptance: a saved filter persists across sessions, applies on open, and the row count matches the filter. Maximum of 20 saved filters per user, with a clear message at the limit.
• Instrumentation: events for filter saved, filter applied and filter deleted, with user role. The product lead reads the weekly count.
• Open questions: should deleted filters be recoverable (owner: design lead, answer by Friday, blocks the delete flow).

Reviewing the spec before the build

Spolsky recommends rereading until every sentence is easy to follow. I add one external check. Give the spec to an engineer who has not seen it and ask for every question it raises, written down as they read. Each question is either an edit to the spec or an open question with an owner. If a first read produces more than five substantive questions, the spec needs another pass before anyone builds from it.

A spec is finished when an engineer can disagree with it specifically. Disagreement that points at a line, a threshold or a non-goal is cheap to resolve in a document and expensive to resolve in a pull request.

Written by Meet Patel — startup operator and growth strategist in Dubai.

Read on themeetpatel.com