Interview study on the practice of software documentation

• Herbert Prähofer
• Ingo Wesp
• Josef Pichler

This report summarizes the results from an interview study which has been conducted among industry partners of the SCCH for assessing the state of practice of software documentation. In particular, the goal was to learn about the industrial practices for software documentation as well as identifying issues with current processes and tools and uncover potentials and demand for automation. Focus was on requirement documentation, architecture and design documentation, and the prevalence of traceability information in documentation. User documentation was not considered.

The study has been conducted in the form of semi-structured interviews with SCCH industry partners. Altogether, 15 interviews about 15 different software projects from 9 organizations were conducted. The interviews were based on pre-prepared questionnaires with the following parts: (i) general information about the interviewee and the software system; (ii) a questionnaire for assessing the different documentation artifacts; (iii) questions for assessing the maintenance of traceability between documentation and code; (iv) open discussion with the goal to discuss problems and possible improvements.

Results show a clear and surprisingly uniform picture regarding requirement documentation. Documenting requirements is mostly done iteratively using an issue tracking system or the like is prevalent in almost all projects. That means, requirements are usually documented per features or issued before it is implemented and not updated after implementation. Interviewee also largely agreed that such documentation is very useful and of high quality. Thus, interviewees did not see a demand for additional tool support for requirement documentation.

Results show a different picture for architecture and design documentation. First, architecture and design documentation seem to be very diverse. Moreover, architecture and design documentation is partial, barely complete and usually not in line with the current system implementation. Interviewees remarked that the effort for maintaining a detailed architecture and design documentation with an evolving system manually would represent a considerable effort and usually does not pay off. Thus, there could be some potential demand for automating documentation generation from source code, which would allow to keep the documentation aligned with the system implementation.

Finally, regarding traceability, interviews showed that in some projects traces between requirements and implementations are maintained. This is achieved by linking entries in the issue tracking systems to commits in the version control system.