Documentation in Continuous Software Development

Abstract

With the introduction of the Agile Manifesto, Lean Software Development, and Dev-Ops, documentation has become lower in quality and lesser in quantity leading to knowledge evaporation. The Agile Manifesto values working software over comprehensive documentation, and Lean Software Development considers everything that does not contribute to customer value as waste. In Dev-Ops, documentation is primarily found in infrastructure-as-code to keep up with continuously changing legislation and demands for fast time-to-market. Next to the developments above, another issue causing knowledge evaporation concerns the reluctance of software developers to write down information about a software product. In general, software developers and other stakeholders dislike reading documentation; in short, TL;DR. New team members must invest substantial time in comprehending the intentions behind the source code, particularly understanding the reasons for its functioning and extracting insights into how it operates, all directly from the source code itself. The source code alone cannot reveal design decisions or their rationale. Consequently, preserving knowledge necessitates primarily capturing design decisions, rationale, architecture and justification. To mitigate knowledge loss, we formulated three primary research questions that subsequently informed the development of a framework consisting of three approaches and their corresponding artifacts. The first question poses challenges due to culture, loss of focus, and a wide array of tools and processes. The second question examines the characteristics of gls{csd}, including cultural traits defined by values, principles, practices, and processes, life cycle attributes of constant change, systematic challenges like lack of control, and the impact of bugs and new features. The third research question proposes a framework with approaches and artifacts. The approaches in the framework are `Just Enough Upfront', ‘Executable Documentation', and ‘Automatic Text Analysis'. ‘Just Enough Upfront' advocates informal whiteboard sketches to communicate the main objectives between stakeholders, a strictly codified interface description between (sub)systems, and a plan of approach. Afterward, developers document design decisions to incorporate progressive insights and deviations from the initially planned objectives. The characteristics of `Executable Documentation' pertain to human-readable requirements and specifications that can be executed. This approach is typically in use when specifications are clearly defined. With ‘Automatic Text Analysis', machine learning with neural networks is used to identify causal relations in text, especially Git comments, for revealing design decisions. As such, this approach assists in retrieving knowledge.