Documentation Work in Agile Teams: The Role of Documentation Formalism in Achieving a Sustainable Practice

As its second guiding principle, agile software development promotes working software over comprehensive documentation. In this paper we investigate alignment between two different documentation practices and agile development. We report upon an experiment conducted to explore the impact of formalism and media type on various dimensions of documentation practice in agile teams. 28 students in 8 teams were divided into two groups: SAD and UML. Group SAD was to update and deliver their high-level software architecture in form of a textual description defined by RUP templates. Group UML was instructed to update and deliver their low-level software design in form of UML models. Our results show that iterative documentation practices led to more extensive and more detailed textual documentation. We found that writing documentation was perceived as a intrusive task leading to task specialization and allocation of documentation to less qualified team members. Consequently, this hampered collaboration within the team. Based in our findings, we suggest that if documentation is to be delivered with the project, producing documentation should be communicated and accepted by the team as a proper product. Furthermore, we argue that codification of internal development knowledge should be a non-intrusive task.