Struggling To Write A Requirements Specifications? – Top 10 Things To Think About
If you cast your minds back to May this year, you may recall that we published an article looking into the reasons why having your requirements detailed in a Requirements Spec is so important. This month we thought that we would revisit this theme to look at some top tips on how to maintain quality and write requirements that are a dream to work with.
After all as the saying goes if something is worth doing, it’s worth doing well.
1. Can you utilise existing templates?
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.
Check #3 – will your requirements be interpreted by everyone in the same way
3. Can you tell one requirement from another?
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.
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?
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.
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?
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
8. Have you been defining compatibility?
It is not unusual for there to be a requirement describing compatibility between an old and new system. Yet this is often an area that requirements specifications fail to address in adequate detail. If your software is to be compatible with other systems or components, don’t leave it up to the software engineers to decide what will make your system compatible, all the while hoping the V&V team will make the same determination. Explicitly state in your specification how you want these different aspects to interact with each other.
Check #11 – is the manner in which different components are to interact with each other clearly stated or open for interpretation
9. Are you focusing on ‘it shall’ or ‘it shall not’?
If you can guarantee one thing, it will be that there are more things that your software shall not do than things it shall. It is very rarely worth stating requirements in the negative, as it tends to calls into question other things the system shall not do and introduce confusion or lack of focus on the actual end target. However, there are exceptions particularly when dealing with safety requirements.
Check #12 – can you justify your ‘shall not’ requirements
10. Are you falling into the vagueness trap?
It may sound like stating the obvious, but the purpose of a requirements specification is to specify the expected behaviours and properties of a software system. So it stands to reason that requirements contained within these documents should be specific rather than vague. However, it is a nasty habit of both customers and engineers to allow vagueness to creep in. Customers like the feeling that they can refine their requirements further down the line when they have a better idea of what they want. Whereas engineers like that a slack requirement gives them more leeway in their implementation. Unfortunately, this is almost never the reality and results in extensive rework, missed milestones and avoidable expenses.
Check #13 – Be specific in your terminology, avoiding weak words such as intuitive, reliable or compatible
Check #14 – Ensure you are defining precisely what the system needs to be or what it needs to do
Check #15 – Don’t allow others to persuade you into keeping your requirements vague