Skip to main content
Enterprise Architecture

What a good software requirements document actually contains

A feature list is not a specification. The documents that produce good software describe decisions, edge cases and what happens when things go wrong.

1 min read671 views

We are often handed a requirements document that is really a wish list: sixty bullet points beginning with "system should". It is not that these are wrong — they are just not decisions, and software is made of decisions.

What is usually missing

The current process, honestly described

Not the official SOP — the real one, including the workaround everyone uses on month-end. If the document does not describe the workaround, the software will not accommodate it, and users will invent a new one.

Edge cases and exceptions

What happens when a purchase order arrives without a rate? When goods are received short? When a customer pays for three invoices with one cheque? These are where the real complexity lives, and they are almost never in the first draft.

Data ownership

For every entity, exactly one system must be the source of truth. Writing "customer master will be synced between CRM and ERP" without naming the owner guarantees a conflict you will resolve badly at 2 a.m.

Non-functional requirements with numbers

"System should be fast" is unbuildable. "Order search returns in under 800ms with 2 million orders, for 40 concurrent users" is a target you can design for and test against.

Acceptance criteria

For each requirement, how will you know it is done? If two reasonable people could disagree about whether something is complete, it is not specified yet.

What can safely be left out

Screen layouts, field-by-field UI descriptions and technology choices. Those belong to design and architecture, and pinning them down in a requirements document usually locks in a worse answer than the one the team would reach later.

A requirements document's job is not to describe the software. It is to describe the business precisely enough that the software becomes obvious.

Found this useful?

Keep reading

Related articles

More from the blog

Other articles worth your time

Browse all

Free consultation

Have a system that needs this kind of thinking?

Tell us what you are working on. The first consultation is free, and you will speak to an engineer.