Best Practices for Writing Requirements (According to Us)

This article will look at the various gold standards out there and explain – upon balance – what we do.

The problem (why care?)

We can agree that when writing technical or business requirements, clarity is essential.

Creating any kind of confusion introduces risk to the entire project. One tester slightly misinterpreting a word used in a requirement can lead to increased costs later either through delivery delays or defects being introduced. Without a doubt, in requirement walkthrough sessions, someone will always asks a question which reveals a tiny interpretation gap in a requirement which I went in to the session thinking was bullet proof. I welcome these challenges as the requirement always ends up better for it.

So the opening question is, what is the best way to write requirements?

What do the official guidelines say about writing requirements?

There are many “fat books” regarding how to write requirements.

The International Institute of Business Analysis (IIBA)

The following is taken from section 7.2.4 of the Business Analysis Body of Knowledge (BABOK) version 3

Atomic: self-contained and capable of being understood independently of other requirements or designs.

Complete: Enough to guide further work and at the appropriate level of detail for work to continue. The level of completeness required differs based on perspective or methodology, as well as the point in the life cycle where the requirement is being examined or represented.

Consistent: Aligned with the identified needs of the stakeholders and not conflicting with other requirements.

Concise: contains no extraneous and unnecessary content.

Feasible: reasonable and possible within the agreed-upon risk, schedule, and budget, or considered feasible enough to investigate further through experiments or prototypes.

Unambiguous: the requirement must be clearly stated in such a way to make it clear whether a solution does or does not meet the associated need.

Testable: Able to verify that the requirement or design has been fulfilled. Acceptable levels of verifying fulfillment depend on the level of abstraction of the requirement or design.

Prioritised: ranked, grouped, or negotiated in terms of importance and value against all other requirements.

Understandable: represented using common terminology of the audience.Misusing words like shall, should, and must can lead to confusion, scope creep, or even contractual disputes. This guide breaks down best practices for using these common requirement terms correctly, ensuring your specs are precise, actionable, and court-proof

The IIBA aligns with the current gold standard of writing requirements, which is:

The IEEE/ISO/IEC 29148-2018

In this standard, the key points that are relevant to this article can be paraphrased as:

1. Use Shall to indicate requirements which are “Must have“. Shall is used as it is legally binding
2. Use Should for non-mandatory goals or guidance. These are not enforceable but are there to indicate a goal
3. Use Will to indicate a statement of fact

NASA have an easy to read checklist for writing requirements which aligns with the above.

Standards in Reality – What will work better for the majority of you reading this article

If we are working internally, there is no real need to strictly follow the above.

Team 1 is not going to take Team 2 to court if a requirement is not met.

Also I would comfortably bet money on the following being true:

1. Your requirements will end up in MS Word, MS Excel or Confluence
2. Your requirements will be reprioritised as your Project progresses

Therefore:

Use plain English and reduce word count

Instead of saying “The system shall allow a user to indicate that they ‘like’ another user’s photo” – make it simpler:

Or we can take this up a level again

Follow a structure

If you are writing a Business Requirements Document, use SMART: Specific, Measurable, Achievable, Relevant, Time-bound.

If you are working Agile, use INVEST: Independent, Negotiable, Valuable, Estimable, Small, Testable.

We will write about these in a future article but both of these pay respect to the standards in an easy to implement manner. No need to carry a 550 page text book around with you.

Why these suggestions help

The IEEE SA would probably not approve, but being realistic:

If you are working with internal teams – they will find the above way of writing easier to read, quicker to review and less open to misinterpretation. Using less words forces the writer to choose their words carefully.

Note that when a reader sees “The system shall…” 50 times in a row, they start skim-reading and miss the nuances. By taking the above mentioned approach, we remove the noise and force the reader to focus only on the unique functionality.

By removing priority from the sentence structure and storing it as an attribute in a column or field (like we do with our requirements assistant, Jessica), we can easily change the priority later.

Closing thoughts

Standards are important. But we do not always have to follow them to the letter. Do what works best for your own team’s work but ensure you are sticking to the fundamentals: clear, unambiguous requirements.