Software documentation: how much is enough?

Abstract

It is a well-known fact that software documentation is, in practice, poor and incomplete. Though specification, design, and test documents-among other things-are required by standards and capability maturity models (e.g., SEI CMM), such documentation does not exist in a complete and consistent form in most organizations. When documents are produced, they tend to follow no defined standard and lack information that is crucial to make them understandable and usable by developers and maintainers. Then a fundamental practical question, which motivated this keynote address, is to better understand what type of documentation is required, what is needed to support its completeness and consistency, and what is the level of precision required for each type of document. These questions cannot be investigated at that level of generality though. Answers are likely to be very context-dependent if they are to be precise. We focus our attention here on object-oriented development and the Unified Modeling Language (UML).