There was a neat article in the July 13 Dr Dobbs Agile Modeling Newsletter.
It basically argued that you could evaluate the quality of a document based on a set of criteria:
C = The percentage of the document that is currently “correct”.
R = The
chance that the document will be read by the intended audience.
U = The
percentage of the document that is actually understood by the intended audience.
F = The chance that the material contained in document will be followed.
T = The chance that the document will be trusted.
The CRUFT rating of the document, with 100% being a bad thing, is
calculated with the following formula:
100% – C * R * U * F * T
I thought this was a neat idea. I want to address the “U” factor that represents the chance that the document will be understood.
We generally have a clear idea in mind of who’s going to read our document – business stakeholders, architects, developers, and testers. What we don’t necessarily do well is to take into account what the people who perform these roles actually know about the system. If one of our objectives is to make our documents consumable by making them understandable, we need to be careful about how we present information.
One technique that I’ve often suggested that my clients use is to make sure that prose which gives context to the problem being solved should be understandable by a 5th grader. When I suggest this, many people insist that the problem is simply too complex. However, this is probably both overcomplicating your problem, and underestimating your 5th grader. If you can’t explain your problem to a 5th grader, can you really explain it to a tester who has no context on the problem? Can you explain it to a business stakeholder who is brand new to his job?
In addition to facilitating communication with some consumers of the document, the act of breaking down a problem into simpler terms is a valuable exercise. It gives us a fresh perspective on the problem, and often allows us to challenge the assumptions that you’ve made in a more complex document.
So take a look at your last requirements document. Could a smart 5th grader understand them?