All About Requirements: September 2013

Documentation is important. Most of us believe this is true - at least to some degree.

Most people would agree with me that documenting business rules and core functionality is important. The reason is that it makes it easier to update and migrate the solution - and more important it enables agility in a world of ever changing business rules.

However, one valid question is: When is the documentation good enough? not an easy question to answer because it depends on your need for details and how critical the functionality is.

Questions you could ask yourself could be:

Do we have documentation describing how the (functionality of the) solution works?

Can we at any time read from documentation how the functionality is implemented and which business rules are addressed?

If not, is that a problem and what is the impact?

Answers to questions like those gives you a hint on how to approach your documentation. Not all your documentation artefacts need the same detail. After creating the documentation or even better after receiving documentation from a vendor it needs to be reviewed and you need to determine if it is good enough - if it meets your quality expectations.

The problem is though, that there are as many opinions about the documentation quality as people looking at it. To cope with that challenge I have created a small tool for evaluating documentation quality. The tool consists of a number of parameters evaluated from a objective perspective and the result is illustrated in a kind of a heat map as shown below.

The scoring of documentation quality is based on taking each documentation element (e.g. functional requirements, use cases, business rules, domain model, etc.) and rate each of them according to criticality and quality.

You will end up with a score for each documentation element as shown below and a corresponding heat-map as shown above.

The Critical Rate as well as the Quality Rate is meant to be as objective as possible.

Therefore the criticality (determining how critical a documentation element is for your solution is determined by a rate from 1-5 based on the criteria shown below:

The Quality rate (Evaluation score) is also determined by a rate from 1-5 and is based on the criteria shown below:

Pay attention to the criteria for rating 5. Only if the question can be answered with a "Yes" AND if it has been verified, rate 5 can be given. So, it's not enough to know that a certain question can be answered with a "Yes", you also need to verify with your own eyes that it is in fact true.

Now that you know the criteria, the first thing to do is to score each of the documentation elements.

Need more Documentation Elements to score? Just add them to the list of elements, add a sheet with questions determining the best practice of that particular element. That way you will improve your documentation evaluation as an on-going process.

Have you become better at documenting a particular element and need that as a new best practice and new benchmark? Simply update the questions needing answers in the elements sheet.

Let's have a look at the scoring sheets for Business Rules, Functionality, and Detailed Functionality.

For scoring Business Rules I have suggested the criteria shown below. Feel free to add your own criteria.

The important thing is to construct the questions so that you can determine what you think constitutes a good documentation quality.

In addition, make sure to use the same questions for every project, so that they are comparable.

For the scoring of the Functional Requirements I have suggested the criteria shown below.

The last element included in my template (make sure to add a sheet for each element) is the Detailed Functional Requirements, shown below.

For the Detailed Functional Requirements I have suggested a slightly different scoring approach, using the COSMIC Function Process approach to determine the level of documentation.

The COSMIC Function Process approach says that the size of a piece of software is determined by the total number of data movements (Create, Exit, Read, Update and Write) summed over all functional processes. Each data movement is counted as a COSMIC Function Point (CFP).

Using the COSMIC Function Process approach you'll be using a standard approach which is easy to apply.

Below you can see how each documentation quality for each data movement is rated according to the COSMIC Function Point approach.