Back to overview

Software Documentation Issues Unveiled

Type of publication Peer-reviewed
Publikationsform Proceedings (peer-reviewed)
Author Aghajani Emad, Nagy Csaba, Vega-Márquez Olga Lucero, Vasquez Mario Linares, Moreno Laura, Bavota Gabriele, Lanza Michele,
Project PROBE - Live Actionable Software Analytics
Show all

Proceedings (peer-reviewed)

Page(s) 1199 - 1210
Title of proceedings Proceedings of ICSE 2019 (41st International Conference on Software Engineering)

Open Access

Type of Open Access Repository (Green Open Access)


(Good) Software documentation provides developers and users with a description of what a software system does, how it operates, and how it should be used. For example, technical documentation (e.g., an API reference guide) aids developers during evolution/maintenance activities, while a user manual explains how users are to interact with a system. Despite its intrinsic value, the creation and the maintenance of documen- tation is often neglected, negatively impacting its quality and usefulness, ultimately leading to a generally unfavorable take on documentation. Previous studies investigating documentation issues have been based on surveying developers, which naturally leads to a somewhat biased view of problems affecting documentation. We present a large scale empirical study, where we mined, analyzed, and categorized 878 documentation-related artifacts stemming from four different sources, namely mailing lists, Stack Overflow discussions, issue repositories, and pull requests. The result is a detailed taxonomy of documentation issues from which we infer a series of actionable proposals both for researchers and practitioners.