Adapting Installation Instructions in Rapidly Evolving Software Ecosystems
Haoyu Gao, Christoph Treude, Mansooreh Zahedi
TL;DR
This work tackles the challenge of maintaining installation-related README content in rapidly evolving OSS ecosystems. It conducts a large-scale qualitative study of 1,168 README commits from 400 GitHub repositories, culminating in a 189-code taxonomy across six update categories and three trigger types. A new installation-focused README template is proposed and validated via online surveys and a pull request study, showing measurable improvements in perceived documentation quality, particularly in structure, understandability, and conciseness. The findings offer actionable guidance for practitioners and lay groundwork for automated documentation tools that integrate human-in-the-loop updates to keep README files accurate and usable as projects evolve.
Abstract
README files play an important role in providing installation-related instructions to software users and are widely used in open source software systems on platforms such as GitHub. However, these files often suffer from various documentation issues, leading to challenges in comprehension and potential errors in content. Despite their significance, there is a lack of systematic understanding regarding the documentation efforts invested in README files, especially in the context of installation-related instructions, which are crucial for users to start with a software project. To fill the research gap, we conducted a qualitative study, investigating 400 GitHub repositories with 1,163 README commits that focused on updates in installation-related sections. Our research revealed six major categories of changes in the README commits, namely pre-installation instructions, installation instructions, post-installation instructions, help information updates, document presentation, and external resource management. We further provide detailed insights into modification behaviours and offer examples of these updates. Based on our findings, we propose a README template tailored to cover the installation-related sections for documentation maintainers to reference when updating documents. We further validate this template by conducting an online survey, identifying that documentation readers find the augmented documents based on our template are generally of better quality. We further provide recommendations to practitioners for maintaining their README files, as well as motivations for future research directions... (too long for arxiv)