Software Requirements Document: What to Write First

What belongs in it, in what order, and what to leave to the people building it.

November 21, 2026
7 min read

A software requirements document is the written description of what a system must do, for whom, and how anyone will be able to tell it is done. It is not a design, a proposal, or a wish list. Its job is to make the disagreement visible before the invoice, so that a fixed price can be fixed, a change can be priced, and an acceptance test can be written by someone who was not in the meeting.

Most projects that go wrong on cost or scope did not skip planning. They skipped writing it down in a form a stranger could check.

What a requirements document actually is

A requirements document states behaviour and constraints that someone else can verify. It says what happens when a customer cancels an order, not that the system should be "user friendly". Design decisions — the database, the framework, the folder layout — belong to the people building it; putting them in the requirements document is how a business takes ownership of technical risk it cannot evaluate.

The test for any line is simple: could two competent developers read it and reach the same conclusion about whether the built system passes? If not, it is a hope, not a requirement.

The seven sections that earn their place

Seven sections carry almost all of the value. Everything else is appendix material, and a document that runs to eighty pages because it repeats itself is harder to price than a short one.

SectionWhat it statesWhat goes wrong without it
Purpose and usersWho uses the system, in what role, to do what jobPermissions get invented mid-build and the first demo is for nobody in particular
Scope and non-goalsWhat is in this release, and explicitly what is notEvery excluded feature is discovered as "obviously included" at acceptance
WorkflowsThe steps of each job, including failure branchesThe happy path is built; refunds, cancellations and retries become change requests
DataWhat is captured, where it comes from, who may see it, how long it is keptMigration, privacy and reporting are treated as follow-on work
IntegrationsEvery external system, its direction, and who owns the credentialsConnector work becomes the largest unpriced line in the project
Non-functional constraintsLoad, availability, browsers and devices, accessibility, response times"Fast enough" is argued about at launch, when it is expensive to change
Acceptance criteriaA checkable statement per requirementNobody can say whether the project is finished

Scope and non-goals is the section clients most often skip and most often regret. Writing "no offline mode, no native app this phase, single currency, English only" costs ten minutes and prevents three months of ambiguity.

Acceptance criteria turn a wish into a requirement

An acceptance criterion is a sentence that can be tested without asking the author what they meant. Write the condition and the outcome, and keep it boring.

  • Bad: "Checkout should be smooth." Testable: "A customer with a saved card completes checkout in three steps or fewer, and a declined card shows the decline reason without losing the cart."
  • Bad: "Reports must be fast." Testable: "An order report for a 12-month range returns within five seconds for a catalog of 50,000 items."
  • Bad: "Admin can manage users." Testable: "An admin can deactivate a user, and that user's session ends within one minute; no data is deleted."

This is what makes fixed pricing possible at all. A vendor can only carry the risk of a fixed price when the thing being fixed is described in outcomes, and the acceptance criteria are where the outcomes live.

What to leave out

Leave out the solution. Naming a framework or a hosting provider before the requirements are written removes the vendor's ability to say "that choice costs more than the alternative" without appearing to argue with the client. Leave out competitor screenshots presented as a specification — a screenshot says what a page looked like, not what the business rule behind it was. And leave out invented numbers: if an estimate has to be given before the requirements exist, give a labelled range with the assumptions attached rather than a figure that will be treated as a quote later.

How to write one in a week

A workable document takes about a week of part-time effort from the person who owns the process. It does not need a business analyst on staff.

  • Day one: list the jobs the system does today, in the words the staff use, including the spreadsheet and the phone call running in parallel.
  • Day two: write the workflows for the three that carry the most money or the most complaints, including what happens when something fails.
  • Day three: list every external system and every file that moves in or out, and name who owns each credential.
  • Day four: write the scope line, the non-goals, and one acceptance criterion per workflow.
  • Day five: hand it to someone who does not do that job and ask them to find a sentence they could read two ways. They will.

Then send it to vendors and ask them to price against it and mark anything ambiguous. Their questions are the cheapest review the document will get, and the pattern in those questions says more about a vendor than their proposal deck does.

What it changes about the contract

With requirements and acceptance criteria in hand, a fixed-price contract becomes a real instrument instead of a guess with a penalty clause. Without one, a fixed price is only fixed for the scope the vendor imagined, and every conversation about the gap is a negotiation rather than a change order. Time-and-materials work gets cheaper too, because the vendor stops building discovery into every invoice.

The same document tells you which buying model you need. If you cannot write acceptance criteria for a workflow, you do not yet know enough to buy that workflow at a fixed price — which is a reason to fund a short discovery phase, not a reason to accept a vague estimate. It is also what lets you compare custom software against an off-the-shelf product honestly: a purchased product's gaps only become visible once the requirements are written down.

Keep two documents separate. The requirements document says what must be true. The statement of work says who does which part, by when, for how much, and what happens if it slips. Merged, you get a document argued over clause by clause and never read for the thing it was written for.

If the project is going to a vendor you have not worked with, the document doubles as a vetting instrument: ask each candidate what they would build first and what they think is missing, and read the answers against the same text. The custom application work at 723 Studios starts from exactly this artefact, because the alternative is estimating a project we described to ourselves rather than one the client described.

Frequently asked questions

How long should a requirements document be?

Long enough to cover the seven sections and no longer. For a first release of a business system that is usually five to fifteen pages plus a table of acceptance criteria. Length is not rigor; a page of testable criteria is worth more than ten pages of narrative description.

Who writes it, the client or the vendor?

The client writes the problem, the vendor writes the solution. In practice the vendor helps structure it, because a good vendor has written dozens and knows which questions expose an unstated rule. If a vendor offers to write the whole document and then price it, the requirements will quietly match whatever they are best at building.

Is a requirements document the same as an SOW?

No. The requirements document describes the system; the statement of work describes the commercial arrangement — parties, deliverables, dates, payment schedule, change process and warranty. Keeping them separate means a change to commercial terms cannot silently rewrite what the software has to do.

How do we handle requirements that change mid-project?

Give each requirement an identifier and price changes against those identifiers. "Modify R-14: the refund window becomes 30 days instead of 14" is arguable in minutes; "the refund rules changed" restarts the estimate.

Do we need one for a small project?

Yes, in a shorter form: one page of scope, non-goals and acceptance criteria. The failure mode of a small project is not missing detail, it is missing agreement about what "done" means, and one page fixes that.

Share this post