How to write a request a developer can build from
A request a developer can build from answers four things: who does this, what they are trying to achieve, what happens today instead, and how you will know it worked. Everything else is detail that can be decided later.
The advice you usually get is “write a detailed spec”, which is bad advice for a small business owner. Detailed specs describe solutions, and you are not the right person to design the solution, that is what you are paying for. What you are uniquely able to describe is the problem.
Four questions do it.
Who is doing this, and what are they trying to achieve?
Not “the user”. A person with a job.
Weak: “Add a reporting dashboard.”
Strong: “On Monday mornings our office manager needs to know which jobs ran over on labour last week, so she can flag them before we invoice.”
The second version rules out a dozen wrong builds. It tells you the frequency (weekly), the audience (one person, not customers), the decision it supports (flagging before invoicing) and the shape of the answer (a list of jobs, not a chart).
What happens today instead?
This is the question people skip, and it is the most valuable one.
Whatever the problem is, someone is already solving it somehow: a spreadsheet, a WhatsApp message, a person who just knows. Describe that. It tells a developer what the real logic is, including the exceptions you would never think to mention.
“She exports the timesheet CSV, pivots it by job number, and compares against the quoted hours in the job folder. Takes about an hour. She skips the jobs under £500 because it is not worth it.”
That last sentence is a business rule you would never have written in a spec, and it will shape the build.
How will you know it worked?
Give a condition, not a feeling.
“Monday review takes ten minutes instead of an hour” is checkable. “Better visibility” is not, and anything you cannot check cannot be finished, which is how projects drift for months while everyone is technically satisfied.
What is the smallest useful version?
Ask yourself what you would accept if you could only have it in one week.
Usually the answer is a fraction of the original request, and usually that fraction delivers most of the value. The rest can follow once you have used the first part and discovered which half of your assumptions were wrong.
What you do not need to include
- Which technology to use. If you specify the database, you have taken a decision away from the person you hired to make it.
- What the screen looks like. Describe what has to be decided on it; let someone who does this for a living arrange it.
- Every edge case. Two or three of the awkward ones is plenty. A good builder will ask about the rest.
- Polished prose. A voice note is fine. Turning it into something buildable is the job.
A shape you can copy
Who: Our office manager, Monday mornings.
Wants: To spot jobs that ran over on labour before we invoice.
Today: Exports timesheets to CSV, pivots by job, compares to quoted hours in the job folder. About an hour. Skips jobs under £500.
Done when: She can see the overruns in under ten minutes without exporting anything.
Smallest useful version: A single list of last week’s jobs where actual hours exceeded quoted hours. No charts, no history.
Four sentences and a boundary. Anyone competent can start from that, and if they have questions they will be the right questions.