A good developer brief is one page that answers six questions: what problem you are solving, who it is for, exactly what is in and out of scope, what already exists, what constraints apply, and how you will know it is done. It does not need technical language. It needs specifics, so that two developers reading it would quote for the same job.
This is different from reporting a bug. A bug report describes something that is broken; we cover that in how to report a website bug. A brief describes something new you want built or changed: a landing page, a booking flow, an integration or a small app.
Why one page?
Long briefs are rarely read closely, and they tend to mix the essential with the nice-to-have. Short briefs force decisions. If you cannot fit the job on a page, it is often two or three jobs, and it is worth splitting them so each can be priced and delivered on its own.
A one-page brief also makes quotes comparable. When three developers quote from a vague email, you get three different interpretations and three prices that cannot be compared. When they quote from the same page, the differences mean something.
What goes in a developer brief?
- The goal. One or two sentences on the business outcome. “Let customers book a free consult online instead of phoning” is better than “new booking page”.
- Who uses it. Customers, staff, or both. On phone or desktop. Anything about them that matters, such as older users or people filling it in on site.
- In scope. A plain list of what must be delivered. Pages, features, fields, emails, integrations.
- Out of scope. What you are deliberately not doing this time. This line prevents more arguments than any other.
- What exists already. Your platform (WordPress, Shopify, Webflow, custom), where it is hosted, the tools it connects to, and any designs or copy that are ready.
- Constraints. Budget range, deadline and why, brand guidelines, and any rules that apply, such as accessibility or privacy requirements.
- Definition of done. How you will check it works. “A test booking appears in the calendar and the customer gets a confirmation email.”
- Who decides. One person who answers questions and signs off.
How do you describe scope without technical knowledge?
Describe behaviour, not technology. You do not need to say “use a webhook”. You need to say “when someone pays, their order should appear in our spreadsheet within a minute”. A developer can work out the how. What they cannot guess is the what.
Walk through the job as a user would and write each step down. Then do the same for the unhappy paths: what should happen if the payment fails, if someone enters a bad postcode, or if the form is submitted twice. These edge cases are where scope quietly grows, so naming them upfront is worth a lot.
Examples help more than adjectives. Link to two or three sites that do something similar, and say what you like about each. “Like this, but with our colours” is a perfectly good brief for a section of a page.
What should you send along with the brief?
- Screenshots or a quick screen recording of the current site or the part you want changed.
- Any designs, wireframes or sketches, even a photo of a hand drawing.
- Final or near-final copy. Unfinished copy is one of the most common reasons small jobs drag on.
- A list of accounts the job touches, so access can be arranged through invited users. See giving a developer access without passwords.
- Your rough budget. It is not a negotiating weakness. It lets the developer suggest the best version of the job that fits.
Never put passwords, API keys or customer data in a brief. List the accounts involved and arrange access separately once the job is agreed.
Questions a good developer will ask you
If a developer quotes without asking anything, be wary. Expect questions like these, and answer them in the brief where you can:
- Who owns the hosting, domain and code, and will the work live in your accounts?
- Is there a staging site to test on, or does work go straight to the live site?
- What happens to the data collected, and who needs to receive it?
- Are there integrations with a CRM, payments or email tool, such as HubSpot or Stripe?
- Who will maintain this afterwards, and do they need any handover notes?
When the brief is not enough
Some projects are too uncertain to brief on one page yet. You might not know whether to extend your current site or build something separate, or how a new app should fit with the systems you already run. That is a sign the first job is a short design or architecture piece, with its own output: a clear plan that can then be briefed and quoted properly. If you are weighing up a spreadsheet replacement, when a spreadsheet should become a small app is a useful starting point.
A template you can copy
- Goal:
- Users and devices:
- In scope:
- Out of scope:
- Platform and existing tools:
- Examples we like and why:
- Budget range and deadline:
- Done means:
- Decision maker:
If you only do three things
Write down the goal in one sentence, list what is out of scope, and define done as something you can test yourself. Those three lines alone make quotes more accurate and handovers much smoother.
If your job is a new landing page or a small site, we quote from a one-page brief like this one. See landing pages and small sites. Landing pages from $900. Small sites up to five pages typically $2,500–$4,000.
