How to Write Good Requirements

What makes a requirement good

A requirement is read by several people who each bring different assumptions: the customer who approves it, the engineer who designs to it and the tester who checks it. A good requirement means the same thing to all of them. The qualities below are widely used in practice, though different organisations phrase them differently.

• Clear. Plain words that a new team member can follow.
• Unambiguous. Only one reasonable interpretation.
• Testable. There is a way to show whether it is met.
• Singular. One idea per statement.
• Necessary. Someone needs it; removing it would leave a gap.
• Feasible. It can be achieved within the constraints.
• Consistent. It does not contradict another requirement.
• Independent of the solution. It states the need, not the design.

The usual shape

Many teams write requirements as a sentence with a subject, a verb and a measurable result: “The [system] shall [do something] [under conditions] [to a stated level].” Using “shall” for what is mandatory is a common convention, and the key point is consistency. If “shall”, “should” and “may” are used, define what each means for your project, for example mandatory, desirable and optional.

Before and after examples

The values below are illustrations only. Real figures come from stakeholders, measurements and the applicable standards.

Vague word.

• Before: “The app shall load quickly.”
• After: “The home screen shall display its content within 2 seconds of launch on the reference device, in at least 95 percent of test runs.”

The second version names what is measured, the limit, the conditions and how often it must hold. Whether 2 seconds is the right target is a decision for the people involved.

Several ideas in one.

• Before: “The unit shall record temperature and humidity, and send an alert, and store data for a month.”
• After, as three statements:
  1. “The unit shall record temperature at intervals of one minute.”
  2. “The unit shall send an alert when the temperature passes a user-set limit.”
  3. “The unit shall retain recorded data for at least 30 days.”

Splitting them lets each be tested, changed or dropped on its own.

Hidden solution.

• Before: “The system shall use a relational database.”
• After: “The system shall store customer records so that a record can be found by name within 1 second.”

The first dictates a design; the second states the need and leaves room for the engineers to choose.

Missing condition.

• Before: “The pump shall run continuously.”
• After: “The pump shall run continuously for 8 hours at ambient temperatures between 5 and 35 degrees Celsius.”

Without conditions, nobody knows what to test.

Passive voice hiding the actor.

• Before: “Errors shall be logged.”
• After: “The controller shall write each fault to the fault log with a timestamp.”

Saying who or what does the action removes a common source of gaps.

Words to be careful with

Some words invite disagreement because they carry no number:

• Fast, slow, easy, user-friendly, robust, flexible, adequate, minimal
• As appropriate, if possible, where practical, etc., and so on
• Normally, usually, generally
• “And/or”, which can be read in more than one way
• Unexplained pronouns such as “it” or “this” when two things were just mentioned

You do not need to ban them entirely, but each one should prompt the question “how would I measure that?” Using plain language for technical audiences, with short sentences and defined terms, helps. A personal glossary or a shared project glossary helps keep terms consistent so that “user”, “operator” and “customer” are not used interchangeably.

Testability in practice

Ask of each requirement: “If I handed this to a tester, could they tell me whether it passed?” If the answer is no, rewrite it. Verification is usually done by test, inspection, analysis or demonstration, and it helps to note which one applies. Writing the check beside the requirement exposes weak wording quickly. Acceptance criteria are one way of making the check explicit for a particular piece of work.

When a quantity is involved, remember that real measurements have limits. A requirement such as “accurate to 1 percent” needs a statement of how and against what reference accuracy will be judged, which connects to measurement uncertainty. Check the units too, and sanity checks on any numbers help avoid typing errors that turn a sensible limit into an impossible one.

Giving each requirement an identity

Give each requirement a unique, stable identifier and keep it even if the text changes. Add useful attributes such as source, priority, status and verification method. Identifiers are the basis for requirements traceability, and they make change discussions precise: people can say “REQ-12” instead of “that bit about the alerts”.

Reviewing a set of requirements

After writing, review the whole set as well as each item:

1. Does any requirement contradict another?
2. Are there gaps, such as a function without a failure case or an interface without a defined behaviour?
3. Are terms used consistently?
4. Can each be traced to a stakeholder need?
5. Has someone who did not write them read them cold? Fresh readers find ambiguity the author cannot see.

A short peer review, run like other design reviews, often catches more than a long solo proofread.

Habits that help

• Write for the reader who knows nothing about the project.
• Prefer short sentences and avoid stacking conditions.
• Record the rationale: a line explaining why the requirement exists helps when it is questioned later.
• Resist gold-plating. Every requirement has a cost, and unnecessary ones add effort and risk.
• Expect to revise. First drafts are rarely good, and that is normal.

Where safety, legal or regulatory matters are involved, follow the standards and the qualified professionals relevant to your industry and country. This article gives general writing guidance only.