For about a year we wrote proper specifications. Thirty or forty pages, every screen described, every state enumerated. They took a week to write and they were genuinely good documents.
Then I went looking for something in one, six weeks into a build, and realised I had not opened it since the day it was signed. Neither had anyone else. We asked the client. They had not either.
What a spec is actually for
Two things, mostly. It creates a shared understanding at the moment it is written, and it settles arguments later. The first is real and valuable. The second almost never happens, because by the time an argument comes up the spec is out of date and everybody knows it.
So we were spending a week producing a document whose useful life was the afternoon we discussed it.
The two things that replaced it
- A one-page scope. What we are building, what we are not, and the number it has to move. Short enough that people re-read it, which is the entire point.
- A deployed URL every Friday. From week two, there is something real to click. Nobody argues about a spec when they can argue about the thing.
What we lost
Being honest about the trade: we lost a certain kind of contractual clarity. When a disagreement comes up about whether something was in scope, the one-pager is less decisive than forty pages would have been.
In practice this has cost us three uncomfortable conversations in two years, and it saved a week of writing on every project. We will take that trade. But if you are working somewhere the relationship is adversarial, keep the spec — it is doing a job the one-pager cannot.