Software developers often spend a considerable amount of time and effort on writing or maintaining documentation. Therefore, it is necessary to assess how much the documentation actually costs and what it may pay back in return. In a Systematic Mapping (SM) literature study, we collected a set of 69 papers published from 1971-2011 and discovered that more empirical evidence is needed to support the cost-benefit analysis of software documentation. This thesis is intended to fill this gap.
We propose Document Cost and Benefit Analyzer (DCBA), a methodology that can be used to comprehensively analyze the costs and benefits of software documentation in software maintenance. To validate DCBA, we report on a case study in which we applied the DCBA methodology to NovAtel Inc. We propose the Cost-Effectiveness Index (CEI) to assess the cost-effectiveness of software documents and explore the relationship between CEI and six other potential impacting factors. Also, we report on a controlled experiment in which 26 students participated. Finally, we propose an automatic visualization tool named DEVis to aid the document evolution analysis.
Our findings include (1) Software documentation delays subjects’ completion of experimental tasks, yet helps improve the code quality and makes it easier for in-experienced maintainers to produce quality code, (2) Maintainers spent 10% of the total task time on reading documents in the experimental context, (3) Programming experience does not impact the benefits or costs of documents that maintainers encounter (4) Document type is a factor impacting the cost-effectiveness and other attributes, including the number of authors, the number of visitors, the number of revisions and document size, are not found significantly impacting the cost-effectiveness of documents, (5) Several document visit patterns exist, including Group-sharing, Publication and One-day-only patterns.