Write a one-page spec before you hire a developer

Why one page is enough

A spec is not a contract and not a technical document. It is the shared picture of what you are buying. When two developers quote from a phone call, they price two different systems. When both quote from the same page, the differences show up as questions you can answer.

One page also forces choices. If it will not fit on one page, you are describing two projects, and the second one can wait.

The seven parts

Write them in this order. Each part is a few lines, and none needs a technical word.

1. 1

   State the goal in one sentence

   Say what changes when the system works. For example: every lead has an owner and a next step, and the boss can see both without asking.

2. 2

   List the people who use it

   Write roles, not names: boss, team leader, agent, admin. Say roughly how many of each, and who must not see what.

3. 3

   Write what each person must be able to do

   Eight to fifteen short sentences that start 'An agent can' or 'The boss can'. Each one is a job, not a screen. Jobs are what a developer prices.

4. 4

   List what the system must hold

   The columns you use today, in plain words: name, phone, source, loan type, amount, stage, next call date. Add documents and notes, and say which data is personal so the developer can plan for it.

5. 5

   Split must-have from later

   Must-have means you cannot start without it. Later means real, but it can wait for version two. Be strict, because most scope creep begins as a small extra.

6. 6

   Say what it connects to

   WhatsApp, your phone system, a spreadsheet you still use, an accounting package. If it connects to nothing, write that.

7. 7

   Say how you will know it works

   Three to five checks you can do yourself on go-live day, such as 'my sheet imports and every phone number is correct'.

How to find the jobs

The hardest part to write is the list of jobs, because people describe the system they imagine rather than the work they do. Get the real list by watching work, not by brainstorming.

• Ask your best agent to walk you through yesterday. What did they open, type, check and write down? Every one of those is a job.
• Ask a team leader what they chase at the end of the day. The answer is usually something the system should show without being asked.
• Ask the boss which question they ask most often. 'Who has not called back?' is a job, and it tells you what the main screen is for.
• Ask each of them what the last system got wrong. The complaints are a free list of what to avoid.

Put some numbers on the page as well, because a developer sizes the work from them. Say how many people will log in, roughly how many new leads arrive in a month, and how many existing records you want moved in. A system for 8 users and a few hundred leads a month is a different job from one for 80 users and several thousand. If you have a budget ceiling or a date that matters, say so and say why. It helps the developer propose something that fits instead of guessing.

A worked example

Here is the whole page for an imaginary agency. Every number is made up. Notice how short each part is, and that nothing in it names a technology.

What to leave out

• Screen designs and colours. Describe the job and let the developer propose the screen. Then react to what you see.
• The technology. Leave it to the developer to propose, and ask why they chose it.
• A long wish list. Everything on the page should be a job you would notice missing on day one.
• Prices. Ask each developer to quote against the spec instead.
• Legal terms. Those belong in the agreement, not in the spec.

It does help to name what you are not building, for example a customer portal or accounting. A line on the page stops the silent assumption that it is included.

Common mistakes

• Describing the Excel sheet instead of the work. 'The same as our sheet, but online' hides the problems the sheet has.
• Listing features instead of jobs. 'Dashboard' means one thing to a boss and another to an agent.
• Leaving out the rules. How is a lead assigned? When is commission earned? A developer cannot guess a rule that lives in your head.
• Having no decision-maker. Name one person who can answer questions within a day. Builds stall on committees.
• Treating the spec as final. It will change after the first look. Agree up front how changes are priced.

What to do with the page

Send the same page to two or three developers. Ask each to tell you, in writing, what they read differently, what they would cut and what it costs. A good developer will have questions. One who quotes in five minutes without any has not read it.

Keep the page afterwards. It is also how you check the finished system, one job at a time. A custom build at NexFlows starts with a short call and a one-page spec, but you can write your own, and any developer should be able to work from it. Our guides on what a custom CRM costs and on whether to build or buy help with the decisions around it.