Beyond accuracy: assessing software documentation quality

Abstract

Good software documentation encourages good software engineering, but the meaning of "good" documentation is vaguely defined in the software engineering literature. To clarify this ambiguity, we draw on work from the data and information quality community to propose a framework that decomposes documentation quality into ten dimensions of structure, content, and style. To demonstrate its application, we recruited technical editors to apply the framework when evaluating examples from several genres of software documentation. We summarise their assessments-for example, reference documentation and README files excel in quality whereas blog articles have more problems-and we describe our vision for reasoning about software documentation quality and for the expansion and potential of a unified quality framework. CCS CONCEPTS • Software and its engineering → Documentation; • Social and professional topics → Quality assurance.

Internet of Things (IoT)-based indoor plant care system

“…The evaluation indicators of the work developed by the developers were mainly the system (i.e., its functionalities and design, including the appearance and size of the device and both mobile and web application interfaces), although the quality of the software code, the software documentation [10] and the project documentation [31] provided, as well as just-in-time delivery, were also considered. At the end of the development period, they achieved varying degrees of compliance, as reflected in the continuous evaluations of the deliverables that resulted from the development of the assigned systems.…”

“…Replacement of a particular sensor should be performed when it fails or at the end of its useful life. The lifespan of individual components may vary and will depend especially on the number or intensity of data acquisition/sending/playback and even more on the climatic conditions (humidity and temperature, among others) of the environment in which they are operating [14,31].…”

Behind the scenes: On the relationship between developer experience and refactoring

“…Because the documentation using commit messages is usually written using natural language, and generally conveys some information about the commit they represent, writing highquality documentation becomes vital for development and maintenance tasks. 82,83 As we found from RQ4 that refactoring contributors who frequently refactor the code tend to less document refactoring activities than the remaining set of developers, we plan to build a generative model based on refactoring documentation quality dimensions to automatically document refactoring properly while ensuring that there is no inconsistency between the code changes and refactoring documentation. This facilitates the automatic generation of refactoring documentation using the list of SAR patterns identified in previous studies.…”

On the Relationship Between Developer Experience and Refactoring

“…• Need for better tools to support the documentation of refactorings for developers at all experience levels. Since the documentation using commit messages is usually written using natural language, and generally conveys some information about the commit they represent, writing high-quality documentation becomes vital for development and maintenance tasks 82,83 . As we found from RQ4 that refactoring contributors who frequently refactor the code tend to less document refactoring activities than the remaining set of developers, we plan to build a generative model based on refactoring documentation quality dimensions to automatically document refactoring properly while ensuring that there is no inconsistency between the code changes and refactoring documentation.…”