Precise Documentation: The Key To Better Software David Lorge Parnas Middle Road Software, Inc. Abstract. The prime cause of the sorry “state of the art” in software development is our failure to produce good design documentation. Poor documentation is the cause of many errors and reduces efficiency in every phase of a software product’s development and use. Most software developers believe that “documentation” refers to a collection of wordy, unstructured, introductory descriptions, thousands of pages that nobody wanted to write and nobody trusts. In contrast, Engineers in more traditional disciplines think of precise blueprints, circuit diagrams, and mathematical specifications of component properties. Software developers do not know how to produce precise documents for software. Software developments also think that documentation is something written after the software has been developed. In other fields of Engineering much of the documentation is written before and during the development. It represents forethought not afterthought. Among the benefits of better documentation would be: easier reuse of old designs, better communication about requirements, more useful design reviews, easier integration of separately written modules, more effective code inspection, more effective testing, and more efficient corrections and improvements. This paper explains how to produce and use precise software documentation and illustrate the methods with several examples. 1 Documentation: a perpetually unpopular topic This paper presents the results of many years of research on a very unpopular subject. Software documentation is disliked by almost everyone. − Program developers don’t want to prepare documentation; their lack of interest is evident in the documents that they deliver. − User documentation is often left to technical writers who do not necessarily know all the details. The documents are often initially incorrect, inconsistent and incomplete and must be revised when users complain. − The intended readers find the documentation to be poorly organized, poorly prepared and unreliable; they do not want to use it. Most consider “try it and see” or “look at the code” preferable to relying on documentation. − User documentation is rapidly being replaced by “help” systems because it is hard to find the details that are sought in conventional documentation. Unfortunately, the “help” system answers a set of frequently occurring questions and is usually incomplete and redundant. Those who have an unusual question don’t get much help.