Adapting Installation Instructions in Rapidly Evolving Software Ecosystems

IF 6.5 1区计算机科学 Q1 COMPUTER SCIENCE, SOFTWARE ENGINEERING

IEEE Transactions on Software Engineering Pub Date : 2025-03-18 DOI:10.1109/TSE.2025.3552614

Haoyu Gao;Christoph Treude;Mansooreh Zahedi

{"title":"Adapting Installation Instructions in Rapidly Evolving Software Ecosystems","authors":"Haoyu Gao;Christoph Treude;Mansooreh Zahedi","doi":"10.1109/TSE.2025.3552614","DOIUrl":null,"url":null,"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. 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.","PeriodicalId":13324,"journal":{"name":"IEEE Transactions on Software Engineering","volume":"51 4","pages":"1334-1357"},"PeriodicalIF":6.5000,"publicationDate":"2025-03-18","publicationTypes":"Journal Article","fieldsOfStudy":null,"isOpenAccess":false,"openAccessPdf":"","citationCount":"0","resultStr":null,"platform":"Semanticscholar","paperid":null,"PeriodicalName":"IEEE Transactions on Software Engineering","FirstCategoryId":"94","ListUrlMain":"https://ieeexplore.ieee.org/document/10931854/","RegionNum":1,"RegionCategory":"计算机科学","ArticlePicture":[],"TitleCN":null,"AbstractTextCN":null,"PMCID":null,"EPubDate":"","PubModel":"","JCR":"Q1","JCRName":"COMPUTER SCIENCE, SOFTWARE ENGINEERING","Score":null,"Total":0}

引用次数: 0

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. 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.

查看原文本刊更多论文

在快速发展的软件生态系统中调整安装说明

README文件在向软件用户提供与安装相关的指导方面发挥着重要作用，在GitHub等平台上的开源软件系统中被广泛使用。软件项目随着它们在动态软件生态系统中的依赖而迅速发展，需要经常更新安装说明。这些说明对于用户开始一个软件项目是至关重要的。尽管它们很重要，但是对于在README文件中投入的文档工作和它们背后的触发器缺乏系统的理解。为了填补研究空白，我们进行了一项定性研究，调查了400个GitHub存储库和1163个README提交，重点关注安装相关部分的更新。我们的研究揭示了README提交中的六个主要类别的更改，即预安装说明、安装说明、安装后说明、帮助信息更新、文档表示和外部资源管理。我们进一步提供了对修改行为的详细见解，并提供了这些更新的示例。我们还研究了文档更新的触发器，这导致了三类问题，包括先前文档中的错误、代码库中的更改和文档改进的需要。根据我们的发现，我们提出了一个README模板，该模板经过了定制，涵盖了与安装相关的部分，供文档维护者在更新文档时参考。通过进行在线调查和拉取请求研究，我们进一步验证了这个模板，发现文档读者发现基于我们模板的增强文档通常质量更好，文档维护者发现它很有用。我们进一步为实践者提供维护他们的README文件的建议，以及未来研究方向的动机。这些建议包括完整性、正确性和最新性，以及信息表示方面的考虑。拟议的研究方向包括开发自动化工具，特别是用于文档更新的工具，以及进行实证研究以加强对文档用户需求的理解。

本文章由计算机程序翻译，如有差异，请以英文原文为准。

求助全文

约1分钟内获得全文求助全文

来源期刊

IEEE Transactions on Software Engineering 工程技术-工程：电子与电气

CiteScore

9.70

自引率

10.80%

发文量

724

审稿时长

6 months

期刊介绍： IEEE Transactions on Software Engineering seeks contributions comprising well-defined theoretical results and empirical studies with potential impacts on software construction, analysis, or management. The scope of this Transactions extends from fundamental mechanisms to the development of principles and their application in specific environments. Specific topic areas include: a) Development and maintenance methods and models: Techniques and principles for specifying, designing, and implementing software systems, encompassing notations and process models. b) Assessment methods: Software tests, validation, reliability models, test and diagnosis procedures, software redundancy, design for error control, and measurements and evaluation of process and product aspects. c) Software project management: Productivity factors, cost models, schedule and organizational issues, and standards. d) Tools and environments: Specific tools, integrated tool environments, associated architectures, databases, and parallel and distributed processing issues. e) System issues: Hardware-software trade-offs. f) State-of-the-art surveys: Syntheses and comprehensive reviews of the historical development within specific areas of interest.