One of the quickest ways to improve your requirements documentation is to have someone else review your work and provide feedback. Of course, the flip side of asking someone to review your work is offering to review their work in return. And, entire project teams can dramatically raise the quality of their output if every member of the team participates in the review and feedback process, both giving and receiving.
Getting direct feedback on your work from a team member or colleague is valuable but I have found that reviewing the work my team mates have done is also a great way for me to improve my own writing.
After reviewing hundreds (thousands?) of requirements documents, and getting feedback on my own work, I’ve come to the conclusion that the logical structure of the writing is as important as the content. Although it may seem that content is more important than structure, in fact it is the structure that makes a document readable and understandable. If your readers cannot easily comprehend your work the content really doesn’t matter.
Here are some guidelines to use when writing or reviewing requirements documentation:
Build from the bottom up but apply structure from the top down. You will have lots of details and they will need to be grouped and summarized from a very detailed level to a high-level. At each level the groupings should make sense and the horizontal and vertical relationships should be obvious. The top down logical structure of the document should be clear as each level below provides support for the level above. Each level of the structure should be a summary of the level below it.
At each lower level of detail the requirements should be grouped together in a way that makes sense. This may seem obvious but it is all too easy to get lost in the details when writing requirements and just end up with lists of features and functions that are not clearly related.
In most cases the items in each group should be ordered in some logical way. Most often this is sequential or chronological, in the order things will happen, but not always. If a chronological ordering is not appropriate, don’t just list things in random order. Think about how the items in the group are related and list them in that order, by priority, proximity, cause and effect, or whatever.
Of course, the rule of seven, plus or minus two says if you have more than nine items in a group you should consider restructuring.
Try to keep structure in mind when you are writing or reviewing requirements documentation. Content and comprehension are equally important.