How to write a software requirements document, short version

A requirements document has one job: to make it possible for someone who was not in the room to build the right thing, and for you to tell afterwards whether they did. Almost every other property people want from it, completeness, contractual protection, the appearance of diligence, works against that job.

This is the version we ask clients for. It is usually between four and eight pages, and it produces better software than the forty page document, for reasons that are structural rather than stylistic.

What the standard actually says

There is a real international standard here, and it is more useful than its reputation suggests. ISO/IEC/IEEE 29148, published on 30 November 2018 and still active, covers the processes and products for engineering requirements across a system or software product's life cycle. It defines what constitutes a well-formed requirement, sets out requirement characteristics and attributes, and describes how the requirements processes apply iteratively rather than once at the start.

That word iteratively is doing a lot of work. The standard replaced IEEE 830, which is the source of the forty page waterfall template most people picture when they hear the phrase. The current standard does not ask for that, and reading it as a demand for exhaustive up-front specification is a misreading that has cost a great many projects a great deal of money.

The five things a short document has to contain

The scope boundary is the section people leave out, and it is the one that prevents the most argument. A sentence saying that the first release does not include multi-branch stock is worth more than three pages describing the features that are included, because it is the only part of the document that can be violated unambiguously.

Write requirements that can fail

A requirement is well formed when there is an observation that would prove it unmet. That single test removes most of the bad ones.

• "The system should be fast" cannot fail. "A stock lookup returns in under two seconds with 50,000 items loaded" can
• "Support multiple users" cannot fail. "Two branch managers can edit different orders at the same time without either losing changes" can
• "User friendly interface" cannot fail, and should be deleted rather than rewritten

Each statement gets a number and keeps it permanently. Numbers are how a change request in month four gets discussed as a change rather than as a disagreement about what was always meant.

Borrow the user story format, but not the ritual

For the parts of the system where a user is trying to accomplish something, the UK Government Digital Service format is hard to beat: as a user, I need to do a thing, so that an outcome happens. The so-that clause is the valuable half. Their guidance makes the point sharply: if you are struggling to write the goal, you should reconsider why you think you need that feature.

The same guidance sets the level of detail, and it is the opposite of what a heavy requirements document does. It advises recording more detail from discussions only when the team is ready to start work on that story, with the initial version carrying just enough for someone to judge its priority. Detail written six months before it is built is detail written against assumptions that will have changed.

Why the long document produces worse software

Three mechanisms, and they compound.

It shifts the conversation from the problem to the artefact. Once the document is forty pages, reviewing it is a day of work, so it gets approved rather than read, and approval of an unread document is the most expensive signature in the project.

It hides the trade-offs. Every real build gives something up. A short document forces those choices into the open, where somebody with authority can make them. A long one lets everything be in scope on paper until the deadline decides instead.

It goes stale invisibly. The build diverges, nobody updates the document because updating it is a project of its own, and you end up with a formal record that no longer describes the system. Our note on how to scope a software project before anyone writes code covers the scoping conversation that should happen before any of this is written down.

Honest limits

This advice is scoped to small and mid-sized business software, which is what we build. If you are working in a regulated domain, medical devices, avionics, financial reporting infrastructure, the exhaustive document is a compliance artefact and its length is not optional. Do not take procedural advice from a general audience note in that situation.

The short document also does not protect you commercially the way people hope. It reduces misunderstanding, which prevents most disputes, but it is not a substitute for a contract, and it will not save a project where the two sides disagree about what the software is for. If timelines are the live question, honest ranges for building a web app is the more useful starting point.