Publication Type

Journal Article

Version

acceptedVersion

Publication Date

1-2025

Abstract

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. Software projects evolve rapidly alongside their dependencies in dynamic software ecosystems, requiring frequent updates to installation instructions. These instructions are crucial for users to start with a software project. Despite their significance, there is a lack of systematic understanding regarding the documentation efforts invested in README files and the triggers behind them. 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. We also studied the triggers for the documentation updates, which led to three categories including errors in the previous documentation, changes in the codebase, and need for documentation improvement. Based on our findings, we proposed a README template tailored to cover the installation-related sections for documentation maintainers to reference when updating documents. We further validated this template by conducting an online survey and a pull request study, identifying that documentation readers find the augmented documents based on our template to be generally of better quality, and documentation maintainers find it useful. We further provide recommendations to practitioners for maintaining their README files, as well as motivations for future research directions. These recommendations encompass completeness, correctness and up-to-dateness, and information presentation considerations. The proposed research directions include the development of automated tools, in particular for documentation updates, and conducting empirical studies to enhance comprehension of the needs of documentation users.

Keywords

Software Documentation, README Files, Qualitative Analysis, Open Source Software, Installation Instructions, Software Ecosystem

Discipline

Software Engineering

Research Areas

Intelligent Systems and Optimization

Areas of Excellence

Digital transformation

Publication

IEEE Transactions on Software Engineering

Volume

51

Issue

4

First Page

1334

Last Page

1357

ISSN

0098-5589

Identifier

10.1109/TSE.2025.3552614

Publisher

Institute of Electrical and Electronics Engineers

Additional URL

https://doi.org/10.1109/TSE.2025.3552614

Download

Share

COinS