Perspectives on Software Development

The 4 Costs of Documentation

A certain amount of documentation is necessary and beneficial to be sure. However, many organizations fall into the trap of believing that more documentation is always better than less. It is imperative that organizations consider the costs associated with documentation. These costs must be weighed against the value of additional documentation. A delicate balance must be struck between too much or too little documentation.

In a software development organization, business value is delivered when working software ships. The primary goal of the organization is delivering business value. Documentation does not contribute directly to business value, though it has the secondary effect of increasing the quality of the business value delivered.

Not sure you agree? How would your customers respond if you delivered immaculate, detailed documentation but no working software system?

Consider the 4 costs of documentation:

Creation Costs

It takes time to create documentation, and time is money.

Monitoring Costs

Documentation is usually reviewed by one or more groups of people to ensure its correctness and consistency. Each person involved devotes time and energy to the review process. A two-hour meeting involving five people burns through 10 hours of work time. Consider the bill rate of all the people in these meetings and you might be surprised at how much a single review costs.

Maintenance Costs

Documentation is only valuable if it is accurate and up-to-date. Invalid documentation is worse than no documentation at all because it can be misleading. Maintenance costs are similar to creation costs. It takes time to keep these documents up-to-date and in agreement with one another. The less tolerant an organization is of dated documentation, the higher the cost associated with meeting the standard.

Missed Opportunity Costs

This cost is the least considered and most insidious. Time spent on documentation is by definition time not spent on productive activities (e.g. writing code). The more time an organization spends on documentation, the less business value it can deliver within a given time frame.

Let me stress that I am not “anti-documentation”. Documentation is necessary and beneficial. At issue is the size and precision of the documentation an organization requires. Finding the right balance requires careful consideration of the costs and benefits in play. Be sure you are getting a return on your investment in documentation.