As you may well know, the purpose of a software requirements specification is to define everything that a software system will be required to do, and act as a support for the design, development and testing process. With such a broad reach across multiple project elements, it is undoubtedly worth taking the time to ensure your documentation is of a high quality.

Maintaining quality whilst writing detailed documentation, such as a requirements specification, is certainly no simple task. However, these top tips will help you write requirements that are a dream to work with.

1. Can you utilise existing templates?

Example Documents

There is so much to remember when putting together substantial documents such as a requirements specification, it wouldn’t take a lot to accidently forget to address an element. By utilising a pre-existing template, complete with important and required section headings you can ensure that all of the necessities will be addressed repeatedly. An additional benefit of utilising a standardised template is that it will promote consistency across your projects, carrying over sections such as formatting and traceability standards.

Check #1 – does your company have a template that you can use as a baseline
Check #2 – are there any templates from an external source or online that meet your requirements

2. Is there room for interpretation?

The English language is packed full of words with more than one meaning, which can change depending on the context that they are used in, and if there is one thing to avoid in requirements documentation it is accidental misinterpretation. An easy way to reduce this risk is to dedicate a section right at the start of the specification to defining how terms will be used throughout the course of the document, and how they should be interpreted in documents referenced as part of the specification. By following the same standards across all of your projects, you can save yourself time when it comes to writing a new specification.

Speech bubbles

Check #3 – will your requirements be interpreted by everyone in the same way

3. Can you tell one requirement from another?

Identify Difference

Reading through a requirements document is hardly an enjoyable task at the best of times, but having to go through a document with no way to identify which requirements are being read makes the process even worse. Taking the time to tag each requirement with an identifier not only improves the ease of reading, but also allows for accurate and reliable referencing and traceability. Making it easier to clarify links between higher and lower level requirements and the specific tests to verify them.

Check #4 – is your document easy to read and are specific requirements easy to find at a glance
Check #5 – can you trace your requirements throughout your requirements document

4. Is there a difference between shall and should?

As a follow on from the previous point it is easy to introduce confusion over requirements if imperative words, such as shall, should, must and will, end up having multiple uses. For most, the word ‘shall’ indicates that the requirement it is attached to must be implemented, whereas the word ‘should’ has a tendency to indicate goals to be addressed. No matter which terms you decide to use in your own documentation, make sure to only use one provision or declaration of purpose for each requirement and that they are used consistently across all of your requirements.

Businessman looking at a line between a to b

Check #6 – is there an agreement on the imperative terms to be used in your documentation
Check #7 – has the agreed usage been documented within the specification template

5. Can you prove it works?

failure or success

The only way to confirm that a requirement has been successfully implemented is to test the software solution and see if the expectations of the requirement have been met. However, this becomes quite problematic if no provisions for verification were included at the time the requirements were written. A good example of how you can ensure requirement testability is to specify reaction timeframes for any output event the software must produce in response to specific inputs, as this gives you what is being tested and the criteria to define a success or a failure.

Check #8 – is it easy to prove either success or failure to meet your requirements

6. Will you remember the reason why?

There is only a small proportion of the people on this earth that have the means to remember every little detail, so the chances of you remembering the reasons behind each and every requirement is next to none. Rather than bury your nice, clean, single sentence requirements in words of explanation and justification, you can include the additional information in a rationale statement. Keeping these two things separate still allows for speedy comprehension, whilst also making your reasoning more evident and removing the chance for ambiguity and re-rationalisation further down the line.

Reminder

Check #9 – do you have the means to be able to recall the reasons behind each of your requirements

7. Will everyone who reads it be able to understand it?

Understanding

Believe it or not, there will come a point where someone will have to read your requirements document. The chances of that someone being the person who wrote the requirements in the first place are minimal, especially when it comes to safety related systems. As a means to keep your requirements clean and concise, it is always beneficial to follow sentence formats where possible. For example, Requirement ID, Object and Provision, Action, Condition followed by the optional Declaration of Purpose/Expected Occurrence.

Check #10 – how easy is it to comprehend and understand your requirements