Helper Guidelines

Users don't know what they want until you show it to them

Focus and Clarity

Focus is the most import aspect of any requirements document. A good requirements document clearly states the objective of the project and defines its scope, to clarify what the project does and does not cover.

A Format for Specifying Requirements

Discussing the many ways in which requirements can be gathered can end up in a heated and impractical debate. The short answer is that you should gather requirements using whichever method works for you, the most important outcome is that the people who need to understand the requirements can do so. If the people that form the project team (client, stakeholders, designers, developers) are happy with the format, that's half the battle won.

This is not to say that all formats of requirements documentation are equal. If you happen to believe that use cases are effective, but your client doesn't understand UML, then it's going to be difficult for them to effectively review the document and identify any errors. This increases the risk of misinterpretation. If the document is too technical, the client is likely to assume it's correct because they don't really know otherwise. These sorts of assumptions don't surface until the work is done, at which point it becomes far more expense to fix. This scenario brings us back to the purpose of a requirements document: to avoid these mistakes in the first place.

So, if you have a format that you, your client and your project team are comfortable with, stick to it.

The Author of the Requirements Document

The art of writing requirements takes great skill and, like writing code, the end result is usually cleaner and more consistent if there's a single author. Great care should be taken in selecting the author. It's a matter of balancing the need for a thorough understanding of the project domain (i.e. the client's business) against understanding the process of software development. An author with a great understanding of the project domain but no experience with software development is a risky choice. So is an author with no understanding of the project domain but extensive experience in software development. Ideally, you want to aim for an author that has both.

The Language of Requirements

If there's only one rule in the use of language then it's to use the same language as your client. It's that simple. If the language is consistent, it greatly lowers the risk of misinterpretation of the requirements. For example, a recent project contains a product catalogue for seeds. In the first draft we categorized the seeds into 'types', 'categories' and 'sub-categories'. While this made sense to us, the client and other stakeholders use the terms 'crop', 'type' and 'variety'. This was bound to cause problems if we didn't use the same terms as the client. A useful technique to avoid this problem is to include a glossary of terms and definitions in the requirements document.

Accuracy is Critical

There's little use writing requirements if they are not an accurate reflection of what the client wants. We've found the best way to deal with this is to walk the client through the requirements, as they'll rarely read them on their own. If it takes five reviews to get it right, then so be it. While it can become a drain to do multiple reviews, persistence pays off. Remember: it costs many times more to fix things in testing than in the requirements phase.

Having said that, don't expect to get the requirements 100% correct. You need to allow for human nature. A requirements document is a statement of 'what' the end result has to achieve. Even with the best intentions in the world, sometimes when we arrive at the end result, it just doesn't work the way we expected -- it's a fact of life. So, the requirements should capture what the client wants, but allow for change as long as the objectives are still being met.

Minimize the Risk of Errant Interpretation

Being clear and unambiguous is difficult. In law, there are rules for interpretation, but even then, those rules are applied by judges who have their own interpretations of how to apply the rules. What does that mean for requirements? It's important to ensure everyone has the same understanding. One of the best ways to minimize the risk of different interpretations is to include examples: diagrams, pictures, or sample data that illustrates what the requirements mean.