How to write a software project brief that gets comparable proposals

Imagine your SaaS customers want to export their account activity for their own reporting. Today, someone on your team prepares the file whenever they ask. You want customers to do it themselves.

You send two developers the same request: “Add a CSV export to the dashboard.”

One proposal covers a button that downloads the rows currently visible on screen. The other covers every record matching the selected dates, permission checks, large exports and instructions for your support team.

The prices are different because the developers have priced different jobs.

A useful software project brief gives them the same starting point. It explains the problem, the people affected, the required outcome, the boundaries and the evidence you will use to accept the work. It also makes uncertainty visible before it becomes a promise.

Start with the work someone needs to do

“Build an export” names a feature. It does not explain why that feature matters or what a usable result looks like.

For this example, a better opening would be:

Customer account administrators need to download their organisation’s activity for a selected reporting period without asking our support team to prepare it. The export must include the agreed fields and all matching records the administrator is authorised to access.

That gives a developer something to investigate. Which fields? How many records? How are permissions enforced? What does the administrator do with the file afterwards?

You do not need to prescribe every technical choice. You do need to distinguish the result that matters from an implementation you happen to have imagined.

What should a software project brief include?

Use the following sections to prepare a conversation, not to produce a document nobody can change.

1. The problem and the intended user

Describe the current workflow and where it breaks down. Identify who needs the change and what they cannot do today. Include a concrete example, with sensitive customer details removed.

For the export, the problem is manual preparation by support. The user is an authorised customer administrator, not every person with a login.

2. The outcome and its boundaries

State what the user should be able to do after delivery, then name what is outside this piece of work.

The first version might cover a customer-initiated CSV download from one existing dashboard. Scheduled reports, new charts and connections to external reporting tools could be excluded. Those may be valuable later; excluding them now prevents an estimate from quietly including them on one side and omitting them on the other.

3. The system, inputs and access

Explain where the change belongs, which existing systems it depends on and what access can be provided. Name the person who can answer questions about the data or current behaviour.

Do not put passwords, API keys or raw customer records in a brief. Describe the access required and provide it through an approved process. A sanitised sample and a test environment may be enough for the initial investigation.

4. The checks that will demonstrate completion

Write observable conditions, not just “the export works”. For this example, agree the following before implementation:

• Fields and format: a UTF-8 CSV with the columns event_id, occurred_at, actor_id and event_type, in that order. Define timestamp formatting and how missing values, commas and line breaks are represented.
• Reporting period: use UTC, including the start instant and excluding the end instant. A September export includes records from 1 September at 00:00 UTC up to, but not including, 1 October at 00:00 UTC. Test records immediately before, exactly at and immediately after each boundary.
• Completeness and access: include every matching record for the administrator’s organisation, not only the current page. Compare the exported IDs and row count with a known test dataset; attempts to export another organisation’s records must return no data.
• Empty and failed exports: agree the exact user-facing messages and retry behaviour. For this example, an empty result displays “No activity found for this period”; a failed export displays “Export failed. Please try again.” Neither should appear as a successful download.
• Volume and time: specify the dataset, environment, load and start/end points for timing. A proposed target could be a complete 10,000-record file downloaded within 30 seconds of the click, in each of three runs on the agreed staging environment with one export running at a time. This is a sample target, not a universal benchmark or a confirmed capability.

If production volumes, simultaneous usage or the safe performance limit are unknown, assign a bounded investigation first. Ask the technical reviewer to establish representative volumes and load, measure the current data path and agree the final acceptance threshold before anyone commits to implementation. Keep the dataset, timings and test results as reviewable evidence.

These are starting points, not a complete test plan. The technical reviewer should help define the relevant security, performance and failure checks before the implementation is committed. See our guide to acceptance criteria and who can accept the work for the decision process behind those checks.

5. The constraints and unresolved questions

Explain any deadline and why it matters. State the budget range if one has been set, required compatibility and dependencies on your team.

Keep facts separate from assumptions. “The current export library can handle our largest customer” is an assumption until someone checks it. Name who will investigate it and whether it could change the estimate.

6. The decision-maker and handover

Name who resolves product questions, who reviews technical evidence and who accepts delivery. One person may hold more than one role, but an external team should not have to guess.

Describe what your team needs to receive: the agreed code and documentation, test evidence, known limitations and operating instructions. Clarify any support period separately. A finished implementation does not imply unlimited ongoing maintenance.

Turn the brief into a fair proposal comparison

Send each provider the same version and ask them to respond against the same headings. If a question changes the scope, update the brief and share the clarification with everyone still preparing a proposal.

Ask each provider to state	What you are trying to establish
Included deliverables and exclusions	Are they offering the same outcome?
Assumptions and required inputs	Which parts of the estimate depend on something not yet confirmed?
Milestones and evidence	What can you inspect before the whole project is finished?
Your team’s responsibilities	How much access, decision-making and review time must you provide?
Price basis and change process	What is priced now, and how will newly discovered work be handled?
Handover and ongoing support	What happens after delivery, and what is a separate engagement?
Estimated duration, earliest start and dependencies	Is the estimate elapsed time or working effort? When could work begin, what must happen first, and how do access or review delays affect delivery?
Currency, taxes and payment schedule	Are totals in the same currency, are applicable taxes included, and what deposit or milestone payments become due when?
Recurring and third-party costs	What hosting, licences, services or usage charges sit outside the project price, who pays them, and what usage assumptions drive them?

A higher price is not evidence of a better proposal. A lower price is not evidence of a shortcut. First make the work comparable. Then judge capability, cost, dependencies and risk together.

When you are not ready for an implementation quote

Suppose nobody knows whether the activity records can be exported without affecting the application under load. Asking for a firm implementation commitment may encourage a confident answer to an unresolved question.

The next piece of work could instead be a bounded investigation: inspect the relevant data path, test a representative sample and return the findings, options and revised scope. Agree those outputs and the effort limit before it starts.

A useful brief is allowed to say “we do not know yet”. It should also say what evidence would let you decide.

A completed brief for the SaaS export example

Here is how the example comes together as one brief. The choices below are sample requirements to confirm against the actual system, not a report of a delivered client project.

Project: Self-service account activity export, first release.

Problem and user: Customer account administrators currently ask support to prepare activity files. They need to download their own organisation’s activity for reporting without that manual handoff.

Required outcome: An authorised administrator selects a reporting period in the existing activity dashboard and downloads all matching records for their organisation as a CSV.

Included / excluded: Include the existing administrator role, date selection, CSV download, permission checks, empty/error messages and support instructions. Exclude scheduled reports, new charts, external reporting integrations and changes to account roles.

Current environment and inputs: Use the existing dashboard, activity data source and organisation permissions. The product owner supplies a sanitised sample and field definitions; the technical lead arranges approved staging access and confirms the data path. No credentials or customer records belong in this brief.

Acceptance evidence: Demonstrate a UTF-8 CSV with event_id, occurred_at, actor_id and event_type. For September, include 1 September 00:00 UTC and exclude 1 October 00:00 UTC. Check both date boundaries, exact IDs and row counts, pagination, cross-organisation access and the agreed empty/error messages. Supply the test dataset description and results for review.

Performance target to validate: Propose 10,000 matching records downloaded within 30 seconds of the click in each of three staging runs, with one export running at a time. The technical lead must confirm whether this represents real customer use and agree the final volume, load and threshold before implementation is priced as a firm commitment.

Constraints and unknowns: Preserve existing permissions and application responsiveness. First investigate the largest reporting period, expected concurrent exports and whether the current data path can meet the target safely. Limit the initial investigation to two working days; return measurements, risks, options and a revised scope. That limit is a proposed scope boundary, not a promised result.

Owners and decisions: The product owner resolves field and workflow questions and records acceptance after the technical lead reviews the evidence. Support reviews the operating instructions. Changes to scope or acceptance targets require the product owner’s agreement and an updated brief.

Timing and commercial request: No delivery date or budget is committed in this example. Ask providers to quote the bounded investigation separately, state their earliest start and estimated elapsed duration, and identify access and review dependencies. Request prices in one agreed currency, with taxes, payment triggers and recurring or third-party charges stated explicitly. Agree the implementation plan after reviewing the findings.

Handover: Provide the code changes, field/format documentation, test evidence, known limitations and support instructions. Quote any post-delivery support period separately.

A software project brief template you can reuse

Project: What are we calling this piece of work?

Problem and user: Who is affected, what happens today, and why does it matter?

Required outcome: What should that person be able to do after delivery?

Included / excluded: Which workflows, users, systems and cases are covered?

Current environment: What exists, what inputs are available, and who owns access?

Acceptance evidence: What conditions will be checked, using what data or demonstration?

Constraints: What dates, budgets, compatibility needs and dependencies matter?

Unknowns: What needs investigation, who owns it, and what decision will it inform?

Owners: Who answers questions, reviews the work and records acceptance?

Handover: What must be delivered so the receiving team can use and maintain the result?

Proposal response: Ask for scope, exclusions, assumptions, milestones, estimated duration, earliest start, dependencies, price basis, currency, taxes, payment schedule, recurring or third-party costs, client responsibilities and support terms.

The next step is a clearer conversation

You do not need a perfect specification before speaking to a specialist. You need enough shared context to discover what is missing without pretending it has already been decided.

In the export example, the most important improvement was not a longer feature list. It was making sure everyone was discussing the same user, the same records and the same conditions for completion.

Have a piece of B2B SaaS work that keeps stalling because the brief is unclear? Tell WKforce what is stuck, including the outcome you need and the questions you have not yet resolved.