Writing Good Requirements

Writing good requirements is hard. Every new specification¹ I read seems worse than the one before. That’s probably just recency bias, but on the chance it is a dying skill I’m sharing this fantastic and short online course from the The University of New South Wales in Sydney.

Several years ago I organized a set of lunch-and-learns around this course that culminated in the following style guide, which I find particularly helpful when it’s been a while and I need a checklist to help re-internalize best practices and get into a flow.

Requirement statements should:

• be singular (not a combination of multiple requirements)
• be a single sentence
• have a consistent sentence form (more on this below)
• avoid negatives (e.g., “The System shall not…”)
• use easily-identified glossary terms (more on this too)
• avoid vague words like “flexible”, “user-friendly”, “if practical”
• use “the” not “a” (the appropriate Fight Club reference is left to the reader)
• use “each” instead of “any”, “all”, or “both”
• use diagrams where helpful
• use mathematical symbols, such as < instead of “less than”
• if quantitative, be an inequality or have a tolerance (something can’t verifiably weigh exactly 2 lbm or have a temperature of precisely 10 °C)
• avoid pronouns like “it”, “that”, “this”, “she”
• avoid conjunctions like “and”, “or”, “then” unless in a strict Boolean sense to combine conditions
• avoid clauses with needless words that can be deleted or captured as rationale

Two tips benefit from further explanation and were important new thought technologies I took from the course. The first is to consistently use the same sentence structure: condition + subject + priority + verb + object + qualification.

For example: [When in the On_State,] + [the System] + [shall] + [display] + [the Local_Time] + [without obscuring the Work_Space.] The minimum set is subject + priority + verb, but considering the complete list forces rigor in identifying a requirement’s scope and intent and speeds up writing because there’s a template to follow.

The second tip is glossary terms. Instead of adding the same verbiage to a bunch of separate requirements, a glossary defines a term once and gives it a proper name. When used in requirement statements glossary terms are formatted to identify them for readers (I prefer hyperlinks with hover text; the course recommends capitalized words joined with underscores, which is probably a (sadly) still-useful holdover from the days of paper).

For example, I wrote a very simple requirement whose entire text was: “The System shall have a Turnaround_Time of < X days.” That is simple and easy to understand, but it doesn’t mean much unless Turnaround_Time is rigorously defined, and doing that within the requirement statement would be ponderous. When does the clock start? When does it stop? Are we counting person-days? Work days? Calendar days? Is it a nominal or worst case? Is there a caveat if unplanned maintenance or repairs are required?

I see so many requirements that would be shorter and easier to read if they leveraged a glossary. A glossary also guards against multiple authors defining a term slightly differently and makes it much faster to update a definition in one place.

But the most important part of any requirement isn’t in the statement at all; it’s the accompanying metadata of rationale and verification approach. The rationale is a breadcrumb that explains to the future why this is a requirement— and if it’s quantitative where the value came from. The worst rationales are tautologies: “We need this requirement to specify the Turnaround_Time.”

No shit.

What’s actually important is knowing how X days was derived, in case the underlying assumptions change (as then we know to revisit the requirement), and because it clarifies intent when it comes to verification.

The verification approach (often called the verification methodology), is more than the method (e.g., test, analysis, inspection). The approach is a sentence or two that describes how we plan to prove our system meets this requirement. If we can’t think of anything smart to say then the requirement is probably crap. If the verification is really time-consuming or expensive then it better be a damn important requirement. The approach is also good place to get into nerdy details like confidence intervals and p-values.

Both the rationale and verification approach can seem tedious in the moment, but combined with the requirements statement checklist are buried treasure because the effort investing in doing things well once will save much more time in the future.