A README is the front door of a project. Most visitors decide within a minute whether to keep reading, and the file they see first is usually README.md. Platforms such as GitHub and GitLab display it automatically on the repository's front page, so it is both documentation and first impression.
What a README is for
A README has three jobs, in this order:
- Tell a stranger what the project is and whether it is for them.
- Get them to a working result quickly.
- Show them where to go next: documentation, support and how to contribute.
Everything else is optional. Notice what is missing from that list: a history of the project, every feature, every configuration flag. Those belong in dedicated documentation that the README links to.
A structure that works
1. A title and a one-sentence description. Say what it does in plain language. "A command-line tool that converts CSV files to JSON" tells a reader more than a clever tagline.
2. A visual or example, if one helps. A screenshot, a short code sample or sample output often explains more than a paragraph.
3. Installation. Give the exact commands, in a code block, that someone needs to run. State prerequisites and versions. If installation has several routes, put the most common first.
4. Quick start or usage. The smallest example that produces a visible result. People copy and paste from this section, so make sure it actually runs.
5. Documentation and configuration. Link out to fuller docs, or give a short table of options if there are only a few.
6. Contributing. A few lines, or a link to CONTRIBUTING.md, saying how to report bugs and propose changes.
7. License. Name it, and link the LICENSE file. Without a licence, others have no clear right to use the code.
Writing tips
- Lead with the answer. Put what the project does before why it was built.
- Use short headings so people can scan.
- Put commands in fenced code blocks with a language tag for highlighting.
- Keep it current. A README that describes last year's interface erodes trust faster than having none.
- Test your instructions on a clean machine or ask someone new to follow them. Gaps you cannot see are obvious to them.
Markdown features that earn their keep
- Fenced code blocks for commands.
- A short table for options or supported formats; see how to write Markdown tables.
- Task lists for a roadmap.
- Relative links to other files in the repository, so they keep working in forks.
- Badges for build status, but sparingly. A row of twenty decorative badges is noise.
Remember that renderers differ; GitHub renders GitHub Flavored Markdown, but a package registry or documentation site may not. See Markdown flavors explained.
Common mistakes
- No description at all, only an installation command.
- Installation steps that skip a prerequisite.
- Screenshots as the only documentation. They cannot be searched, copied or read by a screen reader. Always include text.
- Huge READMEs that try to be the entire manual.
- Broken links after files move.
Check it before you push
Render the file before you commit it. Open it in Docento's Text & Markdown Editor and switch to Preview to confirm headings, tables and code blocks appear as intended, then use the Find box to look for leftover "TODO" notes.
Takeaway
A good README says what the project is, how to start and where to go next, in that order. Keep it short, keep the examples working and link out for the rest.
