We write a spec for anything that takes more than a week. That is about two a week across the company. They all look the same, which is the point: you know where to look before you start reading.
Four headings
- Problem. Who has it, how we know, and what it costs them. One paragraph, with a link to the evidence.
- Not doing. What this spec will not solve, even though someone will ask.
- Proposal. What we will build, drawn if possible, with the smallest version first.
- Open questions. Things we do not know yet, each with an owner and a date.
There is no “Background” and no “Goals” section. Background turns into history nobody needs. Goals turn into a list of nice words. The problem paragraph does both jobs in fewer lines.
The section that saves a week
“Not doing” is the section people skip in their first month and defend in their second. Writing down what is out of scope before the review means the review argues about the proposal, not about everything the proposal could have been.
Example, from the verified pages spec: Not doing: approval workflows, more than one owner per page, verification of individual blocks. Each of these came up. Each was already answered.
Reviews happen in the margin
A spec is shared with the people it affects and gets two working days of comments. If the comments agree, the author resolves them and starts. If they disagree, we meet for 25 minutes with the page open, and the decision is written into the page before anyone leaves.
- Done: Draft shared with engineering, design and support
- Done: Two days of comments
- Done: Disagreements resolved in the page
- To do: Status set to Building in the Specs database
A close cousin is in the gallery as Product spec, written by the Pallet platform team: the same problem-first order, plus a decision log reviewers sign. It is one of the most copied templates we have.