Approaches for Documentation in Continuous Software Development

• Published in: Complex systems informatics and modeling quarterly no. 32; pp. 1 - 27
• Main Authors: Theunissen, Theo, Hoppenbrouwers, Stijn, Overbeek, Sietse
• Format: Journal Article
• Language: English
• Published: Riga Technical University 28.10.2022
• Subjects: agile; documentation; executable knowledge; just enough upfront; machine learning; natural language processing
• ISSN: 2255-9922; 2255-9922
• DOI: 10.7250/csimq.2022-32.01

It is common practice for practitioners in industry as well as for ICT/CS students to keep writing – and reading ¬– about software products to a bare minimum. However, refraining from documentation may result in severe issues concerning the vaporization of knowledge regarding decisions made during the phases of design, build, and maintenance. In this article, we distinguish between knowledge required upfront to start a project or iteration, knowledge required to complete a project or iteration, and knowledge required to operate and maintain software products. With `knowledge', we refer to actionable information. We propose three approaches to keep up with modern development methods to prevent the risk of knowledge vaporization in software projects. These approaches are `Just Enough Upfront' documentation, `Executable Knowledge', and `Automated Text Analytics' to help record, substantiate, manage and retrieve design decisions in the aforementioned phases. The main characteristic of `Just Enough Upfront' documentation is that knowledge required upfront includes shaping thoughts/ideas, a codified interface description between (sub)systems, and a plan. For building the software and making maximum use of progressive insights, updating the specifications is sufficient. Knowledge required by others to use, operate and maintain the product includes a detailed design and accountability of results. `Executable Knowledge' refers to any executable artifact except the source code. Primary artifacts include Test Driven Development methods and infrastructure-as-code, including continuous integration scripts. A third approach concerns `Automated Text Analysis' using Text Mining and Deep Learning to retrieve design decisions.