A short argument for spending more time on the document and less time on the meeting that produced it. With a template.
Most specs are written for the team that is about to build the thing. They describe the requirements clearly enough to start, go through a review meeting, and then sit in Confluence until they are out of date.
The team that has to maintain the work eighteen months later — when the original authors are on different teams, or have left the company, or simply do not remember the reasoning — has no useful record of why the system was built the way it was.
This is a fixable problem.
The wrong mental model
The wrong mental model for a spec is that it is a communication artifact for the kickoff. Write it, align the team, build the thing, move on. On this model, the spec's job is done once the build starts.
The right mental model is that the spec is a maintenance artifact. Its primary audience is the engineer who encounters this system in two years, trying to understand why it behaves the way it does, why the data model looks the way it does, and what alternatives were considered and rejected.
The kickoff alignment is useful. But it is a side effect of writing a good spec, not the purpose of it.
What a spec written for maintainers looks like
A maintenance-oriented spec has a few components that most specs omit.
The problem statement in plain terms. Not "implement X feature." The actual problem being solved, stated in a way that would make sense to someone who did not attend the planning meetings. This section should be stable over time — if the problem statement changes, it probably means you are solving a different problem and the spec should be a new document.
The constraints. What are you not allowed to do, and why? Technical constraints, business constraints, time constraints. These are often the most useful thing for a future maintainer to understand, because they explain why the system is shaped the way it is instead of the more obvious shape.
The alternatives considered. Not a comprehensive survey of everything you thought of — two or three alternatives with a sentence or two explaining why each was not chosen. "We considered X but rejected it because Y" is one of the most useful sentences a spec can contain. It prevents the future maintainer from reinventing the rejected alternative.
The assumptions. What is this design assuming to be true? If those assumptions become false, what changes? This is the section most likely to be useful in a post-mortem.
The open questions at time of writing. What did you not know when you wrote this? This is honest and useful. A spec that presents everything as resolved is usually omitting the parts where you guessed.
A template
The template I use has six sections:
- Problem — What is the problem, who has it, why does it matter.
- Constraints — What we are not allowed to do.
- Approach — What we are doing and why.
- Alternatives — What we considered and rejected.
- Assumptions — What this depends on being true.
- Open questions — What we do not know yet.
That is it. No executive summary. No stakeholder matrix. No appendix with screenshots of the Figma files. Those things have their place in other documents. The spec is the reasoning record.
The time investment
Writing a spec to this standard takes longer than writing a spec to the kickoff standard. On a medium-complexity feature, the difference is probably four to six hours.
Those four to six hours will save more than that in future incident investigations, onboarding time for engineers who join the team after the feature ships, and architectural review meetings where the question "why is it built this way" comes up and no one can answer it.
The ROI is not visible immediately. It is visible the first time someone has to maintain the system without its authors available.
What this changes
If you treat specs as maintenance artifacts, you write them differently. You care less about whether they are polished enough for the review meeting and more about whether they will still be legible in two years. You include the reasoning, not just the conclusion. You note what you were uncertain about.
You also keep them current. Not exhaustively — you do not update the spec every time a minor implementation detail changes. But when the reasoning changes, or when an assumption is invalidated, you update the assumptions section and note the date.
The spec is the memory of the system. Write it for the people who will need that memory.
