# Categorizing the Content of GitHub README Files

arXiv: https://arxiv.org/abs/1802.06997 · HTML: https://mlsanity.com/paper/1802.06997/

## Key facts

- Cited by 18 papers in the map (data through 14 Oct 2026).
- First posted on arXiv 20 Feb 2018.

## Built on by (most cited first, 18 of 18)

- [Agent READMEs: An Empirical Study of Context Files for Agentic Coding](https://mlsanity.com/paper/2511.12884/) (2025)
- [Aspirations and Practice of Model Documentation: Moving the Needle with Nudging and Traceability](https://mlsanity.com/paper/2204.06425/) (2022)
- [On the Use of Agentic Coding Manifests: An Empirical Study of Claude Code](https://mlsanity.com/paper/2509.14744/) (2025)
- [Automatic Analysis of Available Source Code of Top Artificial Intelligence Conference Papers](https://mlsanity.com/paper/2209.14155/) (2022)
- [Evaluating Pre-Trained Models for User Feedback Analysis in Software Engineering: A Study on Classification of App-Reviews](https://mlsanity.com/paper/2104.05861/) (2021)
- [Beyond the Prompt: An Empirical Study of Cursor Rules](https://mlsanity.com/paper/2512.18925/) (2025)
- [ContextCov: Deriving and Enforcing Executable Constraints from Agent Instruction Files](https://mlsanity.com/paper/2603.00822/) (2026)
- [From Anatomy to Smells: An Empirical Study of SKILL.md in Agent Skills](https://mlsanity.com/paper/2607.01456/) (2026)
- [A Dataset of Agentic AI Coding Tool Configurations](https://mlsanity.com/paper/2605.08435/) (2026)
- [Automatically Categorising GitHub Repositories by Application Domain](https://mlsanity.com/paper/2208.00269/) (2022)
- [From Registry to Repository: How AI Agent Skills Are Written, Adapted, and Maintained](https://mlsanity.com/paper/2607.00911/) (2026)
- [FACOS: Finding API Relevant Contents on Stack Overflow with Semantic and Syntactic Analysis](https://mlsanity.com/paper/2111.07238/) (2021)
- [Uncovering Intention through LLM-Driven Code Snippet Description Generation](https://mlsanity.com/paper/2506.15453/) (2025)
- [LLM-based Content Classification Approach for GitHub Repositories by the README Files](https://mlsanity.com/paper/2507.21899/) (2025)
- [Stop Words for Processing Software Engineering Documents: Do they Matter?](https://mlsanity.com/paper/2303.10439/) (2023)
- [Read between the lines -- Functionality Extraction From READMEs](https://mlsanity.com/paper/2403.10205/) (2024)
- [From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation](https://mlsanity.com/paper/2608.20195/) (2026)
- [A Two-Dimensional Study of the Model Context Protocol: Publication and Adoption](https://mlsanity.com/paper/2609.14721/) (2026)

## Abstract (arXiv)

README files play an essential role in shaping a developer's first impression of a software repository and in documenting the software project that the repository hosts. Yet, we lack a systematic understanding of the content of a typical README file as well as tools that can process these files automatically. To close this gap, we conduct a qualitative study involving the manual annotation of 4,226 README file sections from 393 randomly sampled GitHub repositories and we design and evaluate a classifier and a set of features that can categorize these sections automatically. We find that information discussing the `What' and `How' of a repository is very common, while many README files lack information regarding the purpose and status of a repository. Our multi-label classifier which can predict eight different categories achieves an F1 score of 0.746. To evaluate the usefulness of the classification, we used the automatically determined classes to label sections in GitHub README files using badges and showed files with and without these badges to twenty software professionals. The majority of participants perceived the automated labeling of sections based on our classifier to ease information discovery. This work enables the owners of software repositories to improve the quality of their documentation and it has the potential to make it easier for the software development community to discover relevant information in GitHub README files.