The README Everyone Reads First
README.md is the file GitHub displays on a repository's front page. It is the only documentation most projects ever have, and it is read by everyone who arrives — including you, next year, having completely forgotten how to run your own project.
It is worth twenty minutes. It is also the single highest-return twenty minutes in this chapter.
What it must answer
Four questions, in this order, in about a screen and a half.
What is this? One or two sentences, written for somebody who arrived from a search result and knows nothing. Not a slogan — a description.
Who is it for? Or what problem it solves, which is usually the same question.
How do I run it? The actual first command, or the actual first step. Not "install the dependencies" — the command that installs them.
How do I contribute? Even one line: "open an issue before starting anything large" tells a stranger how to approach you.
Markdown in ten minutes
A README is written in Markdown: plain text with a few punctuation conventions that GitHub renders as formatting. This is genuinely all you need:
# A heading ## A smaller heading Normal text, with **bold** and *italic*. - a list item - another one `inline code`, and a link: [the club site](https://example.com)
Code blocks get three backticks on their own line, before and after. Those few conventions cover ninety per cent of every README you will ever read.
Writing for the newcomer
The reader has never seen the project. That means the absolute first command, real example output where it helps, and no "obviously".
This is the same instinct the whole of this book is written with, applied to your own work. The test: could someone who has never spoken to you get the project running from this file alone? If not, the missing step is usually the one that felt too obvious to write down.
# Sandpiper The website for the Sandpiper Birdwatching Club — meeting times, recent sightings, and how to join. ## Running it locally Clone the repository and open `index.html` in a browser. There is no build step and nothing to install. ## The club We meet on the first Thursday of every month at 7pm in the village hall. Visitors are welcome. ## Contributing Photos and sighting reports are very welcome — open an issue with the date, the species, and where you saw it.
Keeping it true
A README describing a version that no longer exists is worse than no README at all, because it costs the reader time before it fails them.
The habit that prevents it: when a change makes the README wrong, fix the README in the same pull request. Not afterwards, not on a list. In the same change, where the reviewer can see both.
The rest of the front page
GitHub also shows a short description and a set of topic tags beside the repository, both set on the website rather than in a file. They cost a minute and they are what makes a repository findable at all.
And the licence, which decides what anyone may actually do with the work. That is the next topic, and it is the one people skip.
- "READMEs are for big projects." A one-paragraph README on a small project is far more useful than a polished one on a project nobody visits.
- "Markdown is a programming language." It is a plain-text formatting convention. The list on this page is essentially all of it.
- "The README should document every function in the project." It should get someone started. Reference documentation is a different job, usually in different files.
- "I will write it at the end, when the project is finished." Projects are rarely finished, and the README is what makes an unfinished one comprehensible.
- On a public repository the README is the whole first impression, and it is what turns a folder of files into something a stranger can actually use.
- Writing one is your first act of documentation — a skill every job asks for and almost no course teaches directly.
- Fixing it in the same pull request as the change is the only habit that keeps it true, and an untrue README is worse than none.
Knowledge Check
What are the four questions a README should answer?
- What it is, who it is for, how to run it, and how to contribute
- The project's history, its authors, its licence, and its future roadmap
- Which files exist, what each one does, and how they call each other
- What problems it has, what is unfinished, and what should not be relied on
Why does this topic say an out-of-date README is worse than none?
- Because it costs the reader real time before it eventually fails them anyway
- Because GitHub ranks repositories lower when their README is inaccurate
- Because an inaccurate README invalidates the repository's licence terms
- Because Git warns about README files that have not changed for a long time
What is the habit that keeps a README true?
- Fix it in the very same pull request as the change that made it wrong
- Review it once a month and update anything that has drifted since then
- Keep it short enough that there is very little in it that can go out of date
- Write it as a list of questions so that nothing in it can become inaccurate
What is Markdown?
- A plain-text formatting convention that GitHub renders as headings and lists
- A programming language used to generate documentation pages automatically
- A file format specific to GitHub that other services cannot display
- A tool that converts source code into readable documentation for a project
You got correct