What to prepare before you talk to a developer (a one-page brief)

You don't need a specification to talk to a developer. Long requirement documents written before anyone has asked questions are usually wrong in the details that matter. What helps is a single page that explains the problem in your words. A good software project brief takes an hour to write and saves weeks of back and forth.

This post gives you a template you can copy, with notes on what to put in each section and what to leave out.

Why one page is enough

A developer's first job is to understand your business, not to receive a list of features. One page forces you to say what matters most. It also gives every developer you talk to the same starting point, so their answers are easier to compare.

Leave the solution open. "We need an app" is a guess at an answer. "Our crews can't see job changes once they leave the office" is a problem a developer can work with. Sometimes the answer is an app. Sometimes it is a setting in software you already own.

The software project brief template

Copy these headings into a document and write a few lines under each.

1. The problem in two sentences

What is going wrong, and what does it cost? Use numbers you actually know.

Example: "Two office staff spend most of Friday copying finished jobs from a spreadsheet into our accounting software. Mistakes mean invoices go out late or wrong a few times a month."

2. Who is involved

List each kind of person who would use the software, and roughly how many of each. Note anyone who must never see certain information.

Example: "The owner, two office staff, eight crew leads on phones. Crew leads should only see their own jobs."

3. How it works today

Describe the current process step by step, including the workarounds. Attach a screenshot of the spreadsheet or a photo of the paper form if you can. The exceptions matter most: what happens when a job is cancelled, split or redone?

4. The tools you already use

Name every tool involved: accounting, payments, payroll, calendar, email, website, spreadsheets. Say which one holds the "true" version of each record.

5. The data

Where do the records live now, how many years of history are there, and how much must come across to a new system on day one?

6. What success looks like

Pick one or two outcomes you would measure in six months.

Example: "Invoices go out the same day a job is finished, and nobody retypes job details."

7. Constraints

Deadlines that are real, such as a busy season or a contract start date. Rules you must follow, such as payroll or privacy requirements. Anything you can't change, such as a tool your accountant insists on.

8. Budget range

A range is fine, and so is "we don't know yet." A range lets a developer suggest what fits instead of quoting the most complete version of everything.

9. Who decides

Name the person who approves the scope and the person who will answer day-to-day questions. If they are different people, say so.

What to leave out

• Feature wish lists. Mention ideas, but don't let them crowd out the problem.
• Technology choices, unless you have a real constraint, such as an existing system that must stay.
• Screen designs. Rough sketches are welcome; detailed mockups before the first conversation tend to lock in early guesses.
• Passwords and sensitive data. Never put logins or customer records in a brief.

What a good developer does with it

A brief is the start of a conversation. Expect questions about the exceptions, the data and the people. Expect someone to suggest a smaller first step than you imagined, or a tool you could buy instead. If a developer quotes a fixed price from the brief alone without asking anything, be careful.

After that conversation, you should receive a written scope: what gets built first, what it costs, and what is left out on purpose. That is how we work. A written scope with a price for the first release usually follows within a week of the first call, and nothing is billed before you approve it.

A shorter version for email

If a full page feels like too much, these four lines are enough to start:

1. What is going wrong, and what does it cost?
2. Who would use the software?
3. Which tools does it need to work with?
4. Is there a deadline or a budget range?

The internal tools and web applications pages show the kinds of problems a brief like this usually leads to.

Send us yours

Paste your brief, or just the four lines above, into our contact form. We reply within one business day. You don't need to have the answer worked out; that is our job.

Cover photo by Mike Tinnion on Unsplash.