Evaluation of Approaches for Documentation in Continuous Software Development

Theo Theunissen, Stijn Hoppenbrouwers, Stijn Hoppenbrouwers, Sietse Overbeek

2023

Abstract

With the adoption of values, principles, practices, tools and processes from Agile, Lean, and DevOps, knowledge preservation has become a serious issue because documentation is largely left out. We identify two questions that are relevant for knowledge acquisition and distribution concerning design decisions, rationales, or reasons for code change. The first concerns which knowledge is required upfront to start a project. The second question concerns continuation after initial development and addresses which knowledge is required by those who deploy, use or maintain a software product. We evaluate two relevant approaches for alleviating the issues, which are ‘Just enough Upfront’ and ‘Executable Documentation’ with a total of 25 related artifacts. For the evaluation, we conducted a case study supported by a literature review, organizational and project metrics, and a survey. We looked into closed source-code and closed classified source-code. We found two conclusive remarks. First, git commit messages typically contain what has been changed but not why source-code has been changed. Design decisions, rationale, or reasons for code change should be saved as close as possible to the source-code with Git Pull Requests. Second, knowledge about a software product is not only written down in artifacts but is also a social construction between team members.

Paper Citation

in Harvard Style

Theunissen T., Hoppenbrouwers S. and Overbeek S. (2023). Evaluation of Approaches for Documentation in Continuous Software Development. In Proceedings of the 18th International Conference on Evaluation of Novel Approaches to Software Engineering - Volume 1: ENASE, ISBN 978-989-758-647-7, SciTePress, pages 404-411. DOI: 10.5220/0011846200003464

in Bibtex Style

@conference{enase23,
author={Theo Theunissen and Stijn Hoppenbrouwers and Sietse Overbeek},
title={Evaluation of Approaches for Documentation in Continuous Software Development},
booktitle={Proceedings of the 18th International Conference on Evaluation of Novel Approaches to Software Engineering - Volume 1: ENASE,},
year={2023},
pages={404-411},
publisher={SciTePress},
organization={INSTICC},
doi={10.5220/0011846200003464},
isbn={978-989-758-647-7},
}

in EndNote Style

TY - CONF

JO - Proceedings of the 18th International Conference on Evaluation of Novel Approaches to Software Engineering - Volume 1: ENASE,
TI - Evaluation of Approaches for Documentation in Continuous Software Development
SN - 978-989-758-647-7
AU - Theunissen T.
AU - Hoppenbrouwers S.
AU - Overbeek S.
PY - 2023
SP - 404
EP - 411
DO - 10.5220/0011846200003464
PB - SciTePress