Abidemi Stephanie Famuyide wrote a post a few days ago titled “15 Tips for Writing Better Requirements“.
I don’t agree with all of the tips. However, there is a lot of good stuff in there. And I particularly like the last one that describes ways to word a requirement.
15 Tips for Writing Better Requirements
- Define one requirement at a time. This implies that the requirement should be atomic. Don’t be tempted to use conjunctions like and, or, also, with and the like. This is particularly important because it can prevent developers and testers from missing requirements.
- Avoid using let-out clauses like but, except, if necessary.
- Each requirement must form a complete sentence with no buzzwords or acronyms
- Each requirement must contain a subject (user/system) and a predicate (intended result, action or condition).
- Avoid describing how the system will do something. Only discuss what the system will do. Refrain from system design; Normally, if you catch yourself mentioning field names and software objects in the requirements specification document, you’re most likely in the wrong zone.
- Avoid ambiguity caused by using acronyms like “etc”, “approx.” and the like
- Avoid the use of indefinable terms like user-friendly, versatile, robust, approximately, minimal impact. Such terms often mean different things to different people
- Avoid rambling, using unnecessarily long sentences or making references to unreachable documents.
- Do not speculate; avoid drawing up wish lists of features that are impossible to achieve. Saying you want a system to handle all unexpected failures is wishful thinking since no system will ever be a 100%
- Avoid duplication and contradictory statements
- Do not express suggestions or possibilities. You can identify these wherever you see statements like might, may, could, ought, etc
- Avoid creating a jigsaw puzzle where requirements are distributed across documents, causing you cross-reference documents. It can make your requirements specification document extremely difficult to read
- Do not forward reference or refer to a requirement that is yet to be defined. Again, your objective is to make the document as much of an easy read as you can
- Use active or positive statements such as “The system shall…” instead of stating “the system shall not…”
- “Shall“ should be used where requirements are being stated, “will” should be used to represent statements of facts; while “should” represents a goal that needs to be achieved
Go and visit her site “Business Analyst Learnings” where she invites you to “rub minds”.
(There is oodles of great information and resources related to Business Analysis.)
Want to learn more?
Below is a selection of resources that I personally feel are relevant to this blog post, and will allow you to get more in-depth knowledge. I do earn a commission if you purchase any of these, and for that I am grateful. Thank you. (Important Disclosure)
|
|
|
|
|
|
|
|
|
|
See more …
Yes, great tips. I also think it helps to differentiate between high level requirements and detailed requirements as they’re used at different times for different purposes. Or perhaps a requirements hierarchy with high level requirements then leading to more detailed requirements as the business domain is better understood.
Hi Tom, I agree with you 100%. The best way, I find, is to be able to keep track of all the requirements – that is, to really manage them. As you say high-level reqs and detailed reqs are used for different purposes. The high-level requirements help you give shape and form to the solution, while the detailed requirements really are useful to go further than just shape and form.
Cheers – appreciate your input!