What to Write Down Before You Talk to a Developer

• A useful project brief describes the problem, the person who has it, and one complete workflow. It doesn't prescribe the code.

• Separate what version one must do from what can wait, and name the things you are deliberately not building.

• List the systems, data, approvals and business rules the developer will have to work around. These are where a small-looking request becomes expensive.

• Write what done means in terms you can check yourself. A customer can submit a request and the right employee can process it is better than build a request feature.

• Send the same brief to every team. The questions they ask will tell you more than the confidence of the proposal they send back.

Three developers can read the same two-paragraph idea and quote three completely different products. One imagined a marketing site with a form. One imagined a logged-in application. One included design, data migration and launch support. The third assumed you would supply all three.

The gap isn't proof that one team is dishonest. It means the input left enough room for each team to invent a different job. Your brief should close the biggest gaps without asking you to become a product manager or technical architect first.

Your brief has one job: give a capable team enough context to ask useful questions. It isn't the final specification, the contract, or a screen-by-screen order. Those come after somebody has tested the assumptions and worked through the details with you.

That distinction protects you. If you try to write the final scope before you understand the work, every missing detail quietly becomes somebody else's assumption. If a developer prices the whole build without asking about those assumptions, the confidence isn't reassuring. It's the first risk.

A good brief also gives every prospective team the same starting point. That makes their questions, exclusions and proposed first steps comparable. It won't make the totals identical, because teams can still recommend different paths. It will make the reason for the difference visible.

This is the step before product discovery. The brief describes what you know. Discovery turns that into validated user flows, priorities, acceptance criteria and a scope someone can responsibly price.

1. The problem in one sentence

Start with what is going wrong or what opportunity has opened, not the app you already pictured. A property manager might write: Residents call the office for tasks they should be able to complete themselves, and staff re-enter the same information into the back-office system. That tells a team what has to improve without deciding that a new portal is automatically the answer.

The UK Government Service Manual's guidance on user needs uses the same discipline: describe what someone needs to do and why, in words they would recognize, rather than naming a feature first.

2. The people who experience it

Name each type of person who touches the workflow. Customer and administrator is often too vague. The resident submitting a maintenance request, the coordinator assigning it, the technician updating it, and the owner who needs a record may all need different information and permissions.

You don't need a polished persona deck. Write what each person is trying to get done, what they can see, and what decision or action belongs to them. If two kinds of user can do different things, say so. Permissions are invisible in a mockup and expensive in a build.

3. One complete workflow

Walk through one real case from the trigger to the result. A customer creates an account, submits a request with a photo, receives confirmation, and sees the status change after an employee responds. Include what happens on the employee side. A list that says login, dashboard, uploads and notifications names parts. A workflow shows how those parts have to work together.

Pick the workflow that carries the most risk or value. If you cannot describe the main one yet, the brief has found the work that needs research before a quote.

4. What version one includes, defers and excludes

Use three lists. Must work in the first release. Useful later. Deliberately outside this project. The third list matters most because it stops a sensible future idea from sneaking into today's estimate.

Keep the first list short. Version one isn't every feature with a smaller label. It is the smallest complete workflow that lets you learn something important or deliver the first useful result. If the list still contains twelve independent workflows, you have a roadmap, not a first release.

5. Systems, data and access

Name the software this work must connect to, the data that already exists, and who controls each account. You don't need to know how the integration works. You do need to say that customer records live in one system, payments happen in another, and the new product cannot become the official accounting record.

Also name what is sensitive. Personal information, payments, health information and access to an existing production system change the questions a responsible team should ask. CISA's Secure by Demand guidance asks software buyers to make security an explicit part of procurement rather than assuming a supplier will infer it.

6. Constraints and decision ownership

Write down the immovable facts. A contract ends on a known date. An existing system must stay live. A pilot has to work on specific devices. A regulator or internal privacy lead has to review a workflow. Separate those from preferences that can change.

Then name one person who can settle product decisions. A team cannot protect a schedule when three stakeholders can reopen the same decision in different meetings. If the decision owner still needs approval from someone else, say who and how long that normally takes.

7. What done lets someone do

Finish each must-have with a sentence you can verify without reading code. A resident can submit a request, attach two photos, and receive a reference they can use later. An employee can see the request, assign it, and record the outcome. If you cannot check the sentence yourself, it isn't acceptance criteria yet.

The brief doesn't need every edge case. It does need enough of these sentences for a team to show how they would turn business language into testable delivery.

Being specific about the problem doesn't mean making technical decisions you aren't equipped to judge. Leave these open unless a real business constraint settles them.

• The tech stack. Tell the team what the product must connect to, where it has to run, and who will maintain it. Let them explain the technology and its tradeoffs. The UK Government Service Manual's technology guidance starts with user needs, existing systems, security and the ability to change later, not a favourite programming language.

• The architecture. You can require ownership, documentation, data access and a clean handoff. You should not draw the database or decide which services talk to each other.

• Every screen. A complete workflow is more useful than a catalogue of pages. The designer may find that two screens should be one, or that the important step happens outside a screen entirely.

• A final launch date. Name the business deadline and what happens if it moves. Ask the team to tell you what can responsibly be a demo, pilot or production release by then.

• The whole future roadmap. Include future ideas in the later list. Do not ask the first quote to price years of uncertainty.

A partner who understands the work should add structure here, not hand the technical decisions back to you. If every question is answered with what do you prefer, you are about to become the unpaid product and technical lead.

Use this as a starting shape. Plain answers are more useful than polished ones.

• Problem: What is happening today, and why is it worth changing now?

• People: Who experiences the problem, who operates the process, and who decides?

• First workflow: What triggers it, what does each person do, and what useful result ends it?

• Must work in version one: The few outcomes the first release cannot omit.

• Later: Useful ideas that do not belong in the first commitment.

• Not part of this project: Boundaries you want every proposal to respect.

• Systems and data: Existing tools, accounts, data sources, integrations and sensitive information.

• Constraints: Deadlines, devices, locations, approvals, operating limits and anything that cannot change.

• Decision owner: One person who can settle product questions, plus anyone whose approval is still required.

• Done means: A few sentences describing what real users can successfully do.

Attach examples only when they explain the workflow. A screenshot of a product you admire can be useful if you say what you admire about it. Build it like this asks a team to copy an answer before they understand your question.

Send the same brief to every team you are considering. Then watch what happens before the proposal arrives.

A useful response restates the problem in its own words, points out the assumptions that still affect scope, asks about the workflow and existing systems, and separates what can be estimated now from what discovery still has to resolve. It may recommend building less. It may recommend testing the idea without custom software first.

A weak response jumps straight to a stack, a feature list and a confident date. It treats every line in your brief as an instruction and every unknown as something that can be priced later. The document can still look polished. The risk sits in what it didn't ask.

This is where the brief connects to choosing a software development partner. You are not judging whether they agree with your idea. You are judging whether they can turn uncertainty into a decision you understand.

When proposals come back, compare scope, exclusions, dependencies, acceptance, ownership and postlaunch responsibility before comparing the total. The pricing model only protects you after the work is defined, which is the longer argument in fixed price versus hourly.

Set a timer for an hour and write the problem, the people and one complete workflow. Add the three boundary lists. Stop before you pick a stack or sketch twenty screens.

If a capable team cannot ask better questions from that page, more detail from you will not fix the conversation. If they can, the brief has done its job. The next step is a discovery process that turns those questions into evidence, user flows and a scope you can actually approve.

If something already exists and you cannot tell whether it is ready to keep building on, use the product readiness assessment instead. A pre-build brief and a review of an existing product answer different questions.