Improving software documentation by separating the concerns of documentation consumers

Documentation is an integral, yet often neglected, part of a software system. It provides information about a software system to a large variety of stakeholders that use the documentation as information source in different tasks including the creation and maintenance of the system or its assessment and usage. Due to the diversity of usage scenarios, the quality of a software documentation can not be assessed objectively, but rather in a subjective, task-dependent way. Furthermore, the different uses of documentation must be understood and taken into account when the quality of software documentation is to be improved. In this paper, an approach is presented that applies the software engineering principle "separation of concerns" to the documentation of software systems to enable an improvement of the current documentation practices. The first step in the approach is the elicitation of the different documentation consumers with their concerns. Based on the elicited concerns, documents are produced that reflect each consumer's perspective on the software system. The presented view-based approach to software documentation has been validated in a series of experiments and industrial applications that are discussed as well.