पाठशाला Pathshala · उत्पाद Utpād, The product · Lesson 13 · Build
The product spec engineers actually want to read
Engineers do not want twenty pages or a one-line ticket. They want one page that names the problem, the user, the number that defines success and what is out of scope, and leaves the how to them.
Pathshala, The Founder Library · 11 October 2026 · 7 min read
Most product specs fail in one of two ways. Twenty pages of screens and edge cases that nobody reads past page three, or a one-line ticket that every engineer reads differently. The spec engineers want sits between them: one page that says what is wrong, for whom, how everyone will know it is fixed and what is not being done.
This lesson gives that page block by block, explains why non-goals do more work than any other part of it, writes one out for a real-looking Indian product and ends with a routine for keeping specs short as the team grows. It assumes a team of two to fifteen engineers and a founder or first product manager doing the writing.
What a spec is for
A spec exists to make one decision visible before engineering time is spent: that this problem, for these users, is worth this much effort, and that success will look like this number. Ben Horowitz’s Good Product Manager, Bad Product Manager put the division of labour plainly. Good product managers crisply define the target, the what as opposed to the how. They communicate in writing as well as verbally and do not give direction informally. Bad ones feel best about themselves when they have figured out how.
That is the first reason engineers stop reading specs. A document that specifies the solution down to the button tells the people who know the system best that their judgement is not wanted, and it is usually wrong about something they could have fixed in a conversation. A spec that defines the problem and the target invites them to find a better solution than the author imagined, which they often do.
The second reason is length. Joel Spolsky’s 2000 essay on functional specs is still the best argument for writing one at all, and his list of parts holds up: one named author, scenarios with realistic users, nongoals, an overview and open issues. What has changed is where the detail lives. A small team shipping weekly does not need every screen written down in advance. It needs the frame that every later decision is checked against.
The one page, block by block
Problem. What is broken, in the user’s terms, with the evidence. Numbers from support tickets or the funnel, two or three direct quotes from interviews, the share of users affected. A problem without evidence is an opinion, and engineers can tell. User. One segment, in one situation, doing one job. Not “SMBs” but “the accountant at a distributor with 40 to 300 retail accounts, at month end”. If the feature is for two segments, write two specs.
Success metric. One number with its baseline, a target and the date by which it should move, plus one guardrail: a number that must not get worse, such as time to complete a task or the support ticket rate. If you cannot name the number, you do not yet know what the feature is for. The [north star lesson](/library/north-star-metric-and-its-input-tree) gives the tree it should hang from. Non-goals. Things that could reasonably be in scope and are deliberately not. More on these below.
Appetite. Basecamp’s Shape Up calls this the amount of time the team wants to spend and says it constrains the solution. Two engineers for three weeks is a different feature from five engineers for a quarter, and saying so up front ends the debate about whether a bigger solution would be better. Shape Up’s pitch has five ingredients: problem, appetite, solution, rabbit holes and no-gos. The one-page spec keeps four of them and hands the solution to the people building it. Open questions. What is not decided, who decides it and by when. Spolsky’s rule applies: resolve them before implementation starts.
A spec that fits this page can be read in four minutes and argued with in fifteen. That is the point of the constraint. A longer document is not more rigorous; it is harder to disagree with, which is a different thing.
Non-goals do most of the work
Malte Ubl’s account of design docs at Google gives the definition worth copying. Non-goals are not negated goals. They are things that could reasonably be goals but are explicitly chosen not to be. “The system should not crash” is not a non-goal. “No support for credit notes in this release” is one, because a sensible engineer might otherwise build it.
Non-goals are where scope is actually decided. Every feature has a halo of adjacent requests that customers will mention and engineers will see as obvious. Written down, the halo becomes a decision the team made once. Left out, it becomes a negotiation that happens in every stand-up for three weeks. Spolsky called them a way to cull features early. Shape Up calls them no-gos and gives the example of ruling out rich-text editing to keep a project inside its appetite.
A good test: after reading the spec an engineer should be able to name three things they will not build. If they cannot, the spec has not drawn the boundary, and the boundary will be drawn instead by whoever pushes hardest. Write four to six non-goals. Include at least one that a customer has asked for, so that the team knows the refusal was deliberate.
A worked example: part payments
A billing app for FMCG distributors in tier-two cities. The spec, in full, would read like this. Problem: retailers settle invoices in two or three instalments, and the app records only full payment. In the last month 31 per cent of support tickets were about recording part payments. Fourteen of twenty distributors interviewed keep a paper khata alongside the app for exactly this, and three of the last five churned accounts named it. User: the distributor’s accountant, managing 40 to 300 retail accounts, reconciling at the end of each day on a laptop in the godown office.
Success metric: the share of part-settled invoices recorded in the app, from close to zero today to 60 per cent within eight weeks of release, measured by comparing instalments recorded with invoices closed. Guardrail: the median time to record a payment stays under thirty seconds. Non-goals: no automatic matching against bank statements; no change to the GST invoice format; no retailer-facing view of balances; no handling of credit notes; no change to the mobile app in this release. Appetite: two engineers for three weeks, shipping behind a flag to ten distributors in week two. Open questions: how a TDS deduction by the retailer is shown against the balance, decided by the founder with the company’s accountant by Friday.
Notice what is missing. There are no screens, no data model, no description of buttons. The engineers will propose those in a short design note of their own. Ubl describes a mini design doc of one to three pages for incremental work; at this scale half a page is often enough. The product spec and the engineering note together are shorter than the twenty-page document they replace, and each is written by the person who knows that half best.
If an engineer cannot say after reading your spec what they will not build, the spec is not finished.
How engineers read a spec
They read it looking for edges. What happens when the payment is larger than the balance, when two people record the same instalment, when the network drops halfway. A spec does not need to answer every edge case, but it must make clear which ones matter to the user and which the engineers may decide. Spolsky’s scenarios do this cheaply: two or three short stories of a real-looking user doing the job, including one where something goes wrong. Engineers derive the edge cases from the stories faster than from a list.
They also read it for honesty. A spec that hides an uncertainty in confident prose loses the reader at the first discovered gap. Put the uncertainty in open questions with a name and a date beside it. Engineers will forgive a spec for not knowing something. They will not forgive it for pretending.
Three habits make the review useful. One author, named at the top, who owns every change. Engineers comment within a day, in the document, before any planning meeting, so the meeting is spent on disagreements rather than on reading. And when a comment changes scope, the change goes into the non-goals or the appetite where everyone will see it, not into a chat thread that half the team missed. The [writing culture lesson](/library/writing-culture-decisions-in-documents) covers the wider habit.
The spec routine, every cycle
Before each planning session, every spec on the table passes six checks. It fits on one page. It has one author’s name and the date of the last change. The problem cites at least one number and one quote. The success metric has a baseline, a target, a date and a guardrail. There are at least four non-goals and one of them is something a customer asked for. The appetite is stated in people and weeks. A spec that fails a check goes back to its author rather than into the sprint.
After release, reopen the spec on the date the metric was due and write one line under it: what the number did. Twelve such lines a quarter are the most honest record of the company’s product judgement it will have, and the next spec gets better because its author has read the last one’s result.
The worked example is illustrative; the definitions and the five-ingredient pitch are from the sources below.