How software documentation helps communication in development teams: A case study on architecture and design documents

Abstract

Communication between developers and within development teams takes place through various communication channels. Software documentation acts as a communication channel among software professionals. But, to what extent documentation can help communication in development teams? [Objective] This paper evaluates how software documentation and specifically architecture and design documents help communication among/within development teams. [Method] We performed a multiple-case study at the IT departments of two Swedish manufacturing companies. The research method followed a qualitative approach consisting of a survey with 24 participants, two semi-structured interviews, and two work diaries. [Results] By performing the case study, the following results were derived: (1) software documentation complements communication rather than replacing it; (2) documentation usage frequency depends on its up-to-dateness and accuracy; (3) the main reasons for using documentation are assistance in development and maintenance phases, knowledge transfer and architecture comprehension, although incomplete/outdated documentation is the main concern; (4) architecture and design documents complement communication channels, and their usage is affected by company policies and education/employment background; (5) knowledge evaporation results in excessive time and cost consumption however, software documentation is a possible remedy to that. [Conclusions] It is concluded that design documents and documentation in general mainly complement communication in development teams and avoid knowledge evaporation, however, their usage depends on their accuracy, company policies and employees’ background.