The cost of ambiguity
'Let the user export their data.' In what format? All the data or one period? Can any user do it? What if there are millions of rows? Each of those questions has an answer, and if it is not written down first, it is decided by whoever is coding, without knowing it, at eleven at night.
Then the review comes, the answer was not the expected one and it gets redone. That cycle, repeated dozens of times, is most of the time lost on a software project.
What a useful specification contains
You do not need a long document. You need five things:
The problem. For whom, what happens to them today and why it matters. One paragraph.
The scope. What the application is going to do, in concrete sentences.
What is out of scope. This is the most forgotten part and the one that prevents the most arguments. Writing 'does not include PDF export' closes a conversation before it starts.
The acceptance criteria. How you will know it is finished, in verifiable terms: 'exports up to one million rows in under a minute in CSV format'.
The quality requirements. Availability, security, cost: what nobody states but everybody expects (we covered this in the architecture series).
The specification as a living contract
- It is the entry gate to construction: with no approved specification, work does not start.
- It is versioned with the code, in the same repository.
- It changes, but in writing. If something changes during construction, the specification is updated first and the code second. That way there are never two truths.
- The acceptance criteria become tests, and those are what decide the acceptance gate.
With the specification approved, the application can be born. And it is best that it is always born the same way.
How we apply it: Platform Engineering.