README

Definitions

1. README is a text file included in a software project that provides essential information about the project: what it does, how to install and use it, how to contribute, and what license it uses. The name README is traditionally written in all capitals so it appears first in a directory listing, a convention dating back to early operating systems. On platforms like GitHub and GitLab, a README.md (written in Markdown) is automatically rendered as the project's front page, making it the first thing visitors see. A good README typically includes a project title and description, installation instructions, usage examples with code snippets, configuration options, API documentation or links to it, contributing guidelines, and license information. For open-source projects, the README is the primary marketing document: it must quickly communicate the project's value proposition and make it easy for new users to get started. Neglecting the README is one of the most common reasons otherwise useful projects fail to gain adoption.

   In plain English: The instruction manual that comes with a software project — the first thing people read to understand what the project does and how to use it.

Etymology

c. 1970

DEC PDP-10 systems include README files as a convention — the name is an imperative: 'Read me before doing anything else'

1975

The convention spreads across Unix; README becomes the expected first file in any software distribution

2008

GitHub renders README.md on repository pages, making the README a project's public face and documentation landing page

Related Terms

• Semantic Web
• Changelog
• Technical Writer
• Changelog Convention
• Contributor Guide
• README Convention
• Run Book Security