How to write a brief that keeps development from spreading
A developer does not need a novel. They need to see what should change in the work, and where the first version ends.
AVERIQ · · updated · 3 min read
Most missed deadlines start not with bad code, but with the sentence “make it like theirs, only better.” From that sentence you cannot tell which action a person should take, or what will count as done. A brief fixes this. It does not have to be a specification of forty pages.
The result first, then the screens
Start with the change in the work. “The manager sees a request from the site and does not enter it by hand.” “The client looks up the status of the order themselves.” “A person understands the service and leaves a request with parameters.” Screens, color, and the names of sections are the next layer. If you start there, the argument in the middle of the project will be about taste, while the task is still unsolved.
Five points without which an estimate is a guess
- Who uses it: a client, an employee, or both. If there are several roles, name them.
- Which action counts as success in the first version.
- What already exists: a site, a spreadsheet, a CRM, records, correspondence. Attach a link if it opens.
- Where the boundary is: what we will not do now, even if it “will be useful later.”
- How you will know the handover happened. One scenario you can walk through by hand.
What the first letter does not need
Do not choose a database, and do not draw a microservice architecture, if you are not ready to maintain it. Do not attach twenty references with no note on which one is about meaning and which one is about mood. And do not hide the exceptions. “We also have a special client” is exactly what later breaks a pipeline that looked simple.
A short statement you can already work from
Wholesalers leave a request on the site. The manager should see it as a list, take it into work, and mark the invoice. The client does not need an account yet. Old requests from email are not moved. It is done when a test request reaches the status “invoice” without a spreadsheet.
This is enough to choose a format. This case is closer to a CRM for the process, not simply a new site. The site stays the entrance. If the client followed the invoice themselves, an account would be added. That is already a service.
When the brief can be handed over
Hand it over when someone from outside can retell the task, and you recognize your own work in the retelling. If every question makes you invent a rule on the spot, this is not a brief yet. It is a subject for a conversation. A conversation is normal. It is a problem when the conversation starts after half the screens have already been drawn.