A README is the front door of a software project: a plain-text file — usually Markdown, named README.md — that explains what the project is, how to install it, and how to use it. It sits at the root of the project folder, and its name is in all caps for one practical reason: caps sort to the top of a directory listing, so it's the first file anyone sees.
It is the most-read file in any codebase. Before anyone runs your code, judges your project, or decides whether to contribute, they read the README. If it's missing, the project looks abandoned or broken — even when the code is fine.
Traditionally: the project's own developers, at the moment the project becomes usable by anyone other than its author — then updated as install steps and features change. A README that says npm install when the project moved to pnpm is worse than a stub, because it actively misleads.
Since roughly 2023 there's a second author in the mix: AI coding assistants. Tools like Claude Code, Cursor and Copilot can generate a first-draft README directly from the codebase — scanning the entry points, dependencies and scripts, and writing the install/usage sections automatically. The draft is usually structurally correct but factually overconfident: it may document commands that exist in the code but not in the actual runtime, or omit the one environment variable that blocks everything. Developers who use these tools review and correct the draft; the ones who don't publish READMEs that read well and lie slightly. Either way, the README is still the developer's responsibility — the AI wrote a draft, not a contract.
There is no enforced standard, but look at ten popular open-source READMEs and seven sections repeat:
| # | Section | What it answers | Typical content |
|---|---|---|---|
| 1 | Name & one-liner | What is this? | Project name, logo, one sentence. Often badges (build status, version, license). |
| 2 | Why it exists | Why should I care? | The problem it solves, sometimes a screenshot or demo GIF. |
| 3 | Installation | How do I get it running? | Exact commands: npm install, pip install, prerequisites, environment variables. |
| 4 | Usage | How do I use it? | Minimal working example, then common cases. Code blocks with expected output. |
| 5 | Configuration | How do I change its behavior? | Options table, config file format, flags. |
| 6 | Contributing | How do I help? | How to run tests, style rules, link to CONTRIBUTING.md if separate. |
| 7 | License & help | What am I allowed to do? Where do I ask? | License name (MIT, Apache-2.0…), link to docs, community links. |
Sections 1–4 are the load-bearing ones: name, why, install, use. If those four are accurate, the README works. Sections 5–7 separate a good project from a rushed one.
The content idea is identical; the extension decides how it renders:
| File | Format | Renders as | Where you see it |
|---|---|---|---|
README.md | Markdown | Formatted page — headings, tables, code blocks, links | GitHub, GitLab, and any Markdown viewer |
README.rst | reStructuredText | Formatted (Python ecosystem convention) | Python packages on PyPI |
README.txt | Plain text | Raw text — symbols like # and ** show as-is | Older projects, source tarballs |
Markdown won: README.md is the default on GitHub, GitLab, Bitbucket and nearly every modern project. If you downloaded one and it shows as raw markup, that's not corruption — it needs a Markdown renderer to display as intended.
A project root usually carries several all-caps text files next to the README. They are not documentation variants — each has a distinct legal or workflow job:
| File | Job | Written by |
|---|---|---|
README.md | What this is, how to start | Developers (now often AI-drafted) |
LICENSE | Legal terms of use — this one has legal force | Chosen from standard licenses (MIT, Apache-2.0, GPL) |
CHANGELOG.md | What changed between versions | Maintainers, per release |
CONTRIBUTING.md | Rules for outside contributors | Maintainers, before accepting the first PR |
CODE_OF_CONDUCT.md | Community behavior rules | Maintainers or org policy |
.gitignore | Files git should not track | Framework scaffolding |
The README links to most of these; it doesn't contain them. A README that tries to include the license text and the contribution rules becomes a wall of text nobody reads — that's what the separate files are for.
Two shifts, both recent. First, generation: AI coding agents now write README drafts from the codebase on request, so "the README was written by hand" is no longer a safe assumption — some AI-generated READMEs document aspirational commands rather than tested ones. Second, reading: AI agents themselves are now a README audience. Coding assistants read the README to understand a project before touching the code, which makes an accurate README more important than ever — an out-of-date install section no longer just confuses a human, it steers an automated agent into running the wrong commands.
| Before AI assistants (pre-2023) | After AI assistants (2023+) | |
|---|---|---|
| Who writes the first draft | The developer, by hand | Often an AI agent, generated from the codebase |
| Who reads it first | A human considering the project | Increasingly, an AI agent evaluating the codebase before acting on it |
| Cost of an out-of-date install section | A confused human emails a question or gives up | An automated agent runs the wrong commands — at machine speed, without asking |
| Accuracy standard | "Mostly right" was acceptable; readers forgive small gaps | Untested claims get executed literally; every documented command must be tested |
| Review loop | Peer review before merging | AI draft + human fact-check of every documented command against a clean machine |
The practical response for a project owner: keep sections 3 and 4 (install and usage) tested, not just written. A README that a fresh machine can follow without a human guessing in between is one that both humans and AI agents can act on.
If you have a README.md on disk — from a downloaded project, an AI agent's output folder, or a repo zip — the fastest way to read it rendered is to drop it onto our home-page viewer: headings, tables and code blocks render in your browser, and the file never leaves your device. If it's on GitHub and you just want to read it without cloning, drag the raw file in the same way — the README viewer page covers that workflow in detail.
Related pages on this site: What is an MD file? covers the .md format itself. README viewer covers reading a README without cloning the repo. Convert Markdown to PDF covers turning a README into a shareable document.