Understanding the production and consumption of software documentation: An empirical analysis and model.
Abdulaziz A. Jazzar · University of Southern California Digital Library · 2014
In spite of numerous research efforts, much software documentation continues to be unusable and/or unused. Current formulation of the software documentation problem is described in terms of two sets of problem variables characterizing the documentation products and processes. This research shows that attributes of the computing setting affect the documentation products and processes. The setting attributes are therefore an important set of problem variables that need to be considered when developing solutions to the software documentation problem. The study empirically examines the effect of three setting attributes on the patterns of production and consumption of documents in real software projects. It proposes and validates a set of hypotheses that define relationships between the documentation settings, products, and processes. The study also shows that accounting for the setting attributes reveals that the software documentation problem is inherently an open system problem. Open systems assume that the information about the world being modeled is never complete. The study indicates that current solution approaches to the documentation problem are solutions only in the closed system perspective. Applying current solutions of the documentation problem does not and cannot therefore generate effective solutions. The verified hypotheses define empirically grounded relationships between the documentation settings, processes, and products. It suggests a documentation model that constitutes a new solution approach to the documentation problem. The model describes mechanisms to achieve solution alternative (local closures) for the software documentation problem. It is therefore a solution approach that addresses the documentation problem as it has always been: an open system problem. (Copies available exclusively from Micrographics Department, Doheny Library, USC, Los Angeles, CA 90089-0182.)