Skip to content
All guides

Before development

Write a software brief that a team can build from.

A useful brief gives everyone the same job to solve. Define users, boundaries, inputs, and the evidence you will use to accept the work—without designing the entire system in advance.

Jump to the checklist

Start with the work someone needs to finish

Describe who does the work today, which tools they use, and where the process breaks down. Then explain what that same person should be able to do after the project. This separates problems software can address from changes that also need a clearer operating process.

Choose a small set of important journeys for the first release. State an observable result: checking a request without asking a colleague, or submitting a complete application for review. Words such as easier and faster need agreed test conditions before they can become acceptance criteria.

Name the users, permissions, and failure cases

Use roles that describe work: requester, reviewer, and administrator. A requirement for member accounts does not explain which records each person can see or change. Record whether one person can have several roles, and who can grant or remove access.

Follow one item from creation to completion. Ask what happens when a document is missing, a request is rejected, or an external service does not respond. These cases affect screens, data, and development effort just as the normal journey does.

  • Visibility

    Decide whether users can see their own records, a department’s records, or all records, and which fields need restricted access.

  • Changes and approval

    Specify who can change status, whether reasons and history are required, and what can change after approval.

  • Failure states

    Describe duplicate submissions, failed uploads, revoked permissions, and interrupted connections.

Draw a boundary around the first release

A feature needs a boundary, not just a name. Reporting might mean an on-screen table, an exported file, or a scheduled email. Those are separate pieces of work. State the data formats, roles, languages, and integrations the release must support.

Keep exclusions beside the included work. When a new request arrives, the team can decide whether it replaces existing work, needs additional budget, or belongs in another release. Mark unknowns explicitly so that discovery work can be planned instead of hidden inside an estimate.

An illustrative scope boundary for a request system
AreaFirst releaseConsider separately
SubmissionOne request type with defined attachment rulesA configurable form builder
ApprovalOne agreed review sequenceConfigurable conditional approval levels
ReportingA status table and an agreed export formatDepartment-specific analytics
NotificationsOne agreed delivery channelMultiple channels and scheduled messages

Prepare the inputs and the people who own them

Collect example documents, existing screens, and sample data with personal information removed. For an integration, provide API documentation, known usage constraints, and a contact who can arrange test access. The brief does not need to contain passwords or production secrets.

Content and approvals are often dependencies for development. Identify who provides copy, images, product information, and translations, and who has authority to approve the result. Include when the operating team can review a test environment.

  • Existing systems and data

    Record whether source code, a database description, or an export exists, and who can authorize test data and migration.

  • Accounts and outside services

    Identify the owners of the domain, hosting, payment service, and accounts that require verification.

  • Constraints

    State the intended launch date, supported devices, approximate budget, and known requirements from the internal IT team.

Describe acceptance as a repeatable check

An acceptance case should describe the starting state, the action, and the expected result. Include test data and an owner for the review. This makes working correctly something the team can demonstrate again, rather than an impression from a screen review.

Include accessibility and performance expectations early. Identify journeys that must work with a keyboard, browsers to test, and the conditions for measuring speed. A performance target needs a measurement method and a clear account of dependencies outside the project’s control.

Finish with the decisions that are still open

Do not invent answers to fill the document. Separate confirmed requirements, estimating assumptions, and questions that need a prototype or a conversation with users. Give each open question an owner and a point at which it must be resolved.

Before work begins, review scope, deliverables, acceptance criteria, change approval, and the person who will operate the system. Payment and ownership terms belong in the project agreement. The brief is a basis for that discussion, not a quotation or a contract.

A checklist for the next team conversation

  • The main job and the current problem are clear
  • User roles and permission boundaries are listed
  • First-release work, exclusions, and unknowns are separated
  • Sample data and integration owners are identified
  • Approvers, important dates, and constraints are recorded
  • Main acceptance cases include failure paths
  • The person taking over operation is identified

Start with a document the team can question and improve. It does not need to be long. It needs to say which work will be finished, who will use it, and who will accept it.

Talk through your project