Writing and Reading Software Documentation: How the development process may affect understanding

Abstract

The effectiveness of documentationwithin a development process is determined by the way in which the intentions of the authors correspond to the expectations of the potential readers. Ideally, the members of a development team share a certain understanding of (the role of) the different types of documentation. However, since one's expectations of a document are personal, and part of a tacitly formed mental model, we can expect different levels of shared understanding between different development team members. We elicited and analyzed the mental models of software documentation from eight members of a single development team. We found indeed different levels of shared understanding between different people. To our surprise, the levels of shared understanding within the team appear closely tied to the development process employed. From Conway's law we know that an organization's structure is mirrored in the structure of the software that the organization produces. Our findings suggest that the organization's development process may likewise be mirrored in the extent to which a development team shares a common frame of reference. Hence, the development process followed may have implications for the effectiveness with which development knowledge can be shared through software documentation.