15 Tips For Writing Better Requirements

/

According to IBM, doing a good job with requirements can save your organization a fortune. Requirements Specification Documents (RSDs) are the primary means of communication between users and developers and should be prepared as carefully as when writing out a contract. The RSD should be considered a binding agreement which contains the conditions governing whether the proposed solution will be acceptable or not. Crafting requirements is not difficult and can be improved through continuous learning and practice. There’s no substitute for good requirements, however. Analysts should pay attention to every little detail ranging from the style, structure and presentation to content, to increase the chances of delivering successful systems.

So, when can you say you’ve written a good requirement?

Though there's no one-size-fits-all approach to writing requirements (there are varying schools of thought on what constitutes a good requirement statement), abiding by this recommended structure will certainly improve the clarity of your requirements.

Ideally, every requirement statement (written from the user's perspective) should contain:

  • A user role that benefits from the requirement
  • A desirable state that the user role wants to achieve
  • A metric that allows the requirement to be tested, where applicable

In addition to the challenge of ensuring that each requirement statement abides by the above structure, here are some useful tips on what to do and what not to do which should be taken into consideration.

15 Tips for Writing a Good Requirement

  1. Define one requirement at a time - each requirement should be atomic. Don’t be tempted to use conjunctions like and, or, also, with and the like. This is particularly important because words like these can cause developers and testers to miss out on requirements. One way to achieve this is by splitting complex requirements till each one can be considered a discrete test case.
  2. Avoid using let-out clauses like but, except and if necessary.
  3. Each requirement must form a complete sentence with no buzzwords or acronyms.
  4. Each requirement must contain a subject (user/system) and a predicate (intended result, action or condition).
  5. 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, programming language and software objects in the Requirements Specification Document, you’re in the wrong zone. 
  6. Avoid ambiguity caused by the use of acronyms like etc, approx. and the like.
  7. Avoid the use of indefinable terms like user-friendly, versatile, robust, approximately, minimal impact, etc. Such terms often mean different things to different people, making it difficult to define their test cases.
  8. Avoid rambling, using unnecessarily long sentences or making references to unreachable documents.
  9. 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% what you want it to be.
  10. Avoid duplication and contradictory statements.
  11. Do not express suggestions or possibilities. You can identify these wherever you see statements with might, may, could, ought, etc.
  12. Avoid creating a jigsaw puzzle where requirements are distributed across documents, causing you to cross-reference documents. This can make your RSD extremely difficult to read.
  13. Do not 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.
  14. Use positive statements such as “The system shall…”, instead of “The system shall not…”
  15. “Shall“ should be used where requirements are being stated, “Will” should be used to represent statements of facts; & “Should” to represent a goal to be achieved.

Do you have any more to add to this list? Don't forget to leave a comment below.

**Also, check out Laura Brandenburg's Requirements Discovery Checklist Pack and the training course on crafting better requirements.**