Focus the Documentation Effort To Maximize the ROUTE

Documentation is a means to communicate. It takes substantial effort to create good documentation, thus we want to ensure that the effort will provide an equal or greater payback. Just as much effort can be wasted on developing great documentation that turns out to be useless as can be wasted on reverse engineering a system with no documentation. The focus must be to maximize the ROUTE: Ratio Of Usefulness To Effort.

For each potential piece of documentation ask the following questions:

• Who is responsible for creating the documentation
• What is the documentation skill level of people in that role
• Who are we trying to communicate it to
• What information are we trying to communicate
• Where is the information best kept
• What is the easiest possible way to reference the information
• What format is best for the information
• Are there requirements to communicate it in certain format
• When should it be documented
• How many times will it be referenced
• What is the maintenance lifetime of the document
• Is it practical to maintain
• Why should it be documented
• What would be the impact of not documenting it

To minimize wasted effort, use the answers to these questions to find the best documentation form for the information in question. The best form will have the highest ROUTE. The ROUTE compares how much information people get from the document (its usefulness) to the amount of time put into creating the document (the effort).

The usefulness of a document varies based on the perspective. From the perspective of the project, a document is useful if it gives the designers more in-site or information and is used by a large audience. From the perspective of the audience, a document is useful if they get the information they need from it and return to it many times. A useful document may be reviewed once by many people who are then able to provide feedback. Another useful document is used many times by one person to find the information they need quickly and easily. These differing perspectives have differing needs and likely different documentation forms.

Minimizing the document creation effort requires looking at the requirements for format, formality, completeness and the available creation aids. The effort in creating a formal document can be substantially reduced if there are tools available to assist in the generation. For example the use of document templates or document generation from code or models lowers the effort and allows the designer to focus on content. Simplifying the format is, however, the best way to minimize effort. The documentation format is really a communication format. Simple forms such as spreadsheets, sticky notes, e-mail messages, and white boards may provide the same usefulness with far lower effort.

One very effective way to maximize the ROUTE in software projects is to document the solution design and its constraints in the code. The only place anyone will ever look to understand how something actually works is the code itself. Therefore, this is where the documentation should be not only for the low level design (the code implementation) but also for the higher level patterns being used. Unit tests provide additional documentation of the understanding of the problem that was being solved as well as the constraints on the design chosen. Code is documentation.

Every industry and enterprise has its own documentation requirements and software engineers must work within those requirements. In the payment card industry PCI DSS is the big one and has all sorts of documentation and lifecycle requirements to go with it. How to maximize the ROUTE of the documentation in each area is a problem in the domain of enterprise architects to solve.