A README is the file a person is meant to read first when they encounter a piece of software. The name itself is an instruction: “read me.” GitHub’s documentation captures the role precisely, noting that “a README is often the first item a visitor will see when visiting your repository,” and that you add one “to tell other people why your project is useful, what they can do with your project, and how they can use it.” The README is the front door, the thing that decides whether a visitor invests another five minutes or closes the tab.
The convention is old, predating the web and modern source hosting by decades. Software distributed on tape and disk has long carried a top-level file explaining what the package is and how to install it, with names such as README, READ.ME, README.TXT, and README.1ST. A small but deliberate trick underlies the all-capitals spelling: in directory listings that sort alphabetically and place uppercase letters before lowercase, a file named in capitals floats to the top of the list, right where a newcomer’s eye lands first. The README is, in effect, designed to be impossible to miss.
What a good README contains has stabilized into a recognizable shape. It typically opens with a one-line description of the project and what problem it solves, then covers installation, a minimal usage example, and pointers to fuller documentation. GitHub’s guidance frames the README as part of a small family of community files, observing that “a README, along with a repository license, citation file, contribution guidelines, and a code of conduct, communicates expectations for your project and helps you manage contributions.” A README that answers “what is this, why should I care, and how do I start” has done its core job.
Source-hosting platforms turned the convention into infrastructure. GitHub recognizes and automatically surfaces a README placed in a few standard locations, and the docs spell out the precedence: “if a repository contains more than one README file, then the file shown is chosen from locations in the following order: the .github directory, then the repository’s root directory, and finally the docs directory.” Because the README is rendered, usually from Markdown, into a formatted page at the top of the repository, it has become the de facto home page of millions of projects, blurring the line between documentation and marketing.
The platform era also added practical guidance that reflects how READMEs are consumed. GitHub recommends using relative links rather than absolute ones to refer to other files in the repository, since “absolute links may not work in clones of your repository,” and advises that “a README should only contain information necessary for developers to get started using and contributing to your project,” with deeper material moved into a wiki or dedicated docs. The README is meant to be the orientation, not the manual.
Taken together, the README is a tiny convention with outsized influence on how software is adopted. It is the place where a project’s culture, clarity, and care are visible at a glance, and it is the single document most likely to determine whether a passing developer becomes a user, a contributor, or neither.