How to Write Good Requirements · Business Analysis Notes

Key ideas#

Two sentence templates#

System perspective (EARS, “Easy Approach to Requirements Syntax”, by Mavin and colleagues): [optional precondition] [optional trigger] the system shall [expected response].
User perspective (Alexander and Stevens): The [user class] shall be able to [action] [object] [conditions or response time]. Name the user class (“Mechanic”), not just “the user”.

Style rules from Wiegers and Beatty#

One modal verb. Use “shall” throughout. Readers, especially across languages, will not notice shades of meaning between “should”, “may”, “will” and “must”. Record priority in a separate attribute: priorities change between iterations, while the wording should stay stable.
Active voice. “The status will be changed” hides who changes it, the system or a person.
Split compound requirements. “And”, “or”, “also” and “and/or” usually signal several requirements in one. If two parts need different tests, they are different requirements. “Unless” and “except” hide a second branch; write the main rule and the exception separately.
Positive wording. Rewrite double negatives. Functionality that is deliberately out of scope belongs in the limitations and exclusions of the vision and scope document, not as a negative requirement in the software requirements specification (SRS). Mark deleted requirements with a status instead of erasing them.
Exact boundaries. “Up to 5 days” and “5 to 10 days” leave day 5 unclear. Say “inclusive” or “more than”.
No “A/B” terms. “Shipping/fulfillment team” could mean synonyms, two teams, “and” or “or”. Pick one meaning.
Tables for variants. Many similar requirements (say, every combination of format and region) are clearer as a table with ID suffixes. An explicit “N/A” cell shows a deliberate gap.

The right level of detail#

Write more detail when the work is for an external client, development or testing is outsourced, the team is distributed, tests are written from requirements, estimates must be accurate, or traceability is required. Less detail is fine for internal work with closely involved customers, experienced developers, a direct precedent such as replacing an existing system, or a packaged solution.

A quick test is to count the tests a requirement needs. A few similar tests mean the level is right. Many different tests mean several requirements are stuck together. The book’s example is a single line about voice commands that hides a whole speech-recognition subsystem.

Weak words and how to fix them#

Weak word or phrase	Fix
acceptable, adequate, reasonable	State the criterion you will judge by
fast, efficient, immediate	Give a measurable time limit
improved, better	Give the size of the improvement
user-friendly, simple	Describe observable characteristics, e.g. task time
and/or	Choose “and” or “or”
between X and Y	Say whether X and Y are included
including, such as, etc.	Give the full list or point to it
usually, in most cases	Say what happens in the other cases
as appropriate, if possible	Explain who decides and how

The authors’ wider point: adverbs and evaluative adjectives make a requirement subjective, which makes it ambiguous, which makes it untestable.

Quick checks for hidden gaps#

Symmetry. Save needs load; create needs delete. If one half is missing, ask why.
Complex logic. Three yes/no conditions give eight combinations. List them all in a decision table.
Exceptions. Every “when it works” needs a “when it fails”.
The absurd reading. Try to find a silly but literal reading. “The status page shall refresh at intervals of not less than 60 seconds” allows one refresh a year. If the absurd reading fits the text, rewrite.

Wiegers and Beatty also warn against analysis paralysis: aim for requirements good enough to proceed at an acceptable level of risk.

Example: before and after#

Weak requirements from The Workshop, a fictional bike-repair chain:

Before	Problem	After
The booking page should be fast and user-friendly.	Two needs, both unmeasurable; “should”	95% of slot searches shall show results within 2 seconds. A first-time customer shall be able to complete a booking without help within 3 minutes in usability testing.
Mechanics and front-desk staff can update and/or close jobs.	Compound; “and/or”; unclear who does what	A Mechanic shall be able to change a job’s status from In progress to Ready for collection. Front-desk staff shall be able to close a job after the customer has paid.
The job status will be changed when parts arrive.	Passive voice; who acts?	When the supplier confirms delivery of all parts for a job, the system shall change the job status from Waiting for parts to Ready to repair.
Repairs under $100 are approved automatically; repairs over $100 need customer approval.	Exactly $100 is undefined	Repairs of $100 or less are approved automatically. Repairs of more than $100 need customer approval.
The system shall not send notifications unless the customer has not opted out.	Double negative	The system shall send repair notifications only to customers who have notifications switched on.
The system shall save the booking.	No failure case	Add: if the booking cannot be saved, the system shall keep the entered data and ask the customer to try again.

Checklist#

Uses a template and names the user class.
One “shall”; priority recorded separately.
Active voice: the actor is clear.
One requirement per statement; no “and/or”.
No weak words without a measure.
Boundaries say inclusive or exclusive.
Each success case has a failure case.
No absurd literal reading fits the text.
Detail matches the context (outsourced, distributed, regulated).

Sources and further reading#

K. Wiegers, J. Beatty. Software Requirements, 3rd ed. Microsoft Press, 2013, ch. 11 (guidelines for writing requirements; EARS template by Mavin et al.; user-perspective template by Alexander and Stevens).