To write a README, create a README.md file in the top level of your project and answer four things fast: what the project is, why it exists, how to install it, and how to use it. Open with a clear title and one-line description, then add installation steps, a usage example, configuration, contributing rules, and a license. Write it in Markdown, keep it scannable, and put the most important information first.
That is the short version. The rest of this guide walks through how to write a README one section at a time, with a small markdown snippet for each so you can see the exact shape before you type. If you would rather study finished files, our gallery of README examples breaks down real projects section by section. For the wider picture of documenting a codebase, see how to document code. This post is the step-by-step how-to.
What is a README and where does it go?
A README is a plain-text file that introduces your project. It sits in the top-level directory, and code hosts like GitHub, GitLab, and Bitbucket render it automatically on the repository page. That makes it the first thing a visitor reads before they look at a single line of code.
Name the file README.md. The .md extension marks it as Markdown, a lightweight formatting syntax that turns # into headings and **text** into bold. Uppercase is the tradition so the file stands out, but lowercase works too. One file, one location, rendered everywhere your code lives.
1. Start with a clear title and one-line description
The top of the file is your billboard. Lead with the project name as an H1, then a single sentence that says what it does in plain words. No jargon, no marketing. Someone skimming ten repos should understand yours in five seconds.
# Foobar
Foobar is a Python library for handling word pluralization.
That one line carries a lot of weight. It tells a reader the language, the category, and the job all at once. If you cannot describe the project in one sentence, write that sentence first and let it sharpen the rest of the file.
2. Add a description: what it does and why
Below the title, expand into a short paragraph or two. Explain what the project does specifically, the problem it solves, and why someone would pick it over the alternatives. This is where context lives. A reader who got past your one-liner wants to know if this fits their need.
## About
Foobar converts English words between singular and plural forms,
including irregular cases like "goose" and "phenomenon". It was
built to replace brittle regex rules in content pipelines with a
single, tested function.
Keep paragraphs to three to five lines. If your project has standout features or background worth noting, a short bullet list of Features fits well here. Resist the urge to write a wall of text. People scan READMEs; they rarely read them top to bottom.
3. Write installation steps
Tell people exactly how to get the project running. Assume the reader is new and wants no ambiguity. List the real commands inside a fenced code block so they can copy and paste without guessing. Name the package manager, because not everyone uses the same one.
## Installation
Use pip to install foobar:
pip install foobar
If the project only runs in a specific context, say a particular language version or operating system, add a short Requirements subsection above the commands. The goal is to remove every reason a reader might fail before they even start. Working software in two commands beats a perfect description in ten.
4. Show usage with examples
Installation gets people set up; usage shows them the payoff. Include the smallest working example you can, and show the expected output where it helps. A reader who sees a real call and a real result trusts the project faster than one who reads a paragraph about it.
## Usage
import foobar
foobar.pluralize("word") # returns "words"
foobar.pluralize("goose") # returns "geese"
foobar.singularize("phenomena") # returns "phenomenon"
Keep the inline example short. If you have richer scenarios, link out to an examples folder or a docs page rather than dumping everything into the README. The README earns its keep by getting someone to a first success, not by documenting every edge case.
5. Document configuration and options
If your project takes flags, environment variables, or config files, give them a section of their own. A short table reads better than prose here, since people scan for the one option they need. List the name, what it does, and the default value.
## Configuration
| Option | Description | Default |
|---------------|------------------------------|---------|
| `FOOBAR_LANG` | Language ruleset to load | `en` |
| `--strict` | Fail on unknown words | `false` |
Zero-config tools can skip this entirely. Do not invent settings to fill space. If there is one important environment variable, document that one and move on. Configuration sections grow naturally as the project does.
6. Explain how to contribute
If you want help, say so and say how. Tell people whether you accept contributions, how to set up a dev environment, and how to run the tests. Explicit steps lower the barrier for a first pull request, and they double as notes to your future self.
## Contributing
Pull requests are welcome. For major changes, open an issue first
to discuss the direction.
To run the test suite:
npm install
npm test
Please update tests as appropriate.
For busy projects, split detailed guidelines into a separate CONTRIBUTING.md. GitHub links to that file automatically when someone opens an issue or pull request. A "Contributing" heading in the README, even a short one, signals the project is open to outside help.
7. State the license
Tell people what they are allowed to do with your code. For open-source projects this is not optional; without a license, the default is that nobody can legally reuse your work. One line pointing to a recognized license is enough.
## License
[MIT](LICENSE)
Pick a standard license rather than writing your own terms. MIT, Apache 2.0, and GPL cover most cases, and tools like choosealicense.com help you decide. Keep the full text in a LICENSE file and link to it from the README.
8. Add badges and visuals
Badges are the small status images you see at the top of many READMEs: build passing, current version, license, test coverage. They convey trust at a glance. Services like Shields.io generate the markdown for you.
Visuals help too. For anything with a UI or a CLI, a screenshot or a short GIF demonstrates the project faster than words. Place badges right under the title and visuals near the usage section. Both are optional, so skip them for tiny utility scripts where they would just be noise.
A copy-paste README template
Here is the full skeleton, every section from above in order. Drop it into a new README.md, delete the parts that do not apply, and fill in the rest. The indentation marks code blocks so the template stays as a single fenced block you can copy in one go.
# Project Name
One-line description of what the project does.
## About
A paragraph or two explaining what the project does, the problem it
solves, and why someone would choose it. List standout features here.
## Installation
Steps to install. Name the package manager and any requirements.
npm install project-name
## Usage
The smallest working example, with expected output.
import project from "project-name"
project.run() // does the thing
## Configuration
| Option | Description | Default |
|----------|--------------------|---------|
| `OPTION` | What it controls | value |
## Contributing
How to set up a dev environment and run tests. Link to
CONTRIBUTING.md for full guidelines.
## License
[MIT](LICENSE)
A short do and don't checklist
Run your README against this list before you commit it. Most weak READMEs fail on the same few points, and they are quick to fix.
Do:
- Put the title and one-line description in the first screen
- Use real, copy-pasteable commands in fenced code blocks
- Keep paragraphs to three to five lines and use bullet lists
- Show expected output in your usage example
- Use descriptive link text, not "click here"
Don't:
- Bury installation steps under paragraphs of background
- Write a wall of text with no headings or lists
- Invent configuration options or features to fill space
- Skip the license on a public project
- Let the README drift out of date as the code changes
When a README is no longer enough
A README is the right tool for a single project that one file can explain. The problem starts when it tries to do too much. Once you are pasting in API references, multi-page tutorials, and a changelog, the file turns into a scroll nobody finishes, and the four questions a README should answer fast get lost.
That is the signal to split documentation out of the repository. When your README starts doing too much, tools like Docsio generate a full branded docs site from your existing content in minutes, so the README can go back to being a clean front door that links to the deeper material. The README stays short; the detail moves somewhere built to hold it. If you want a sense of how lean a strong README can be, the README examples post shows several that stop at the right place.
For teams comparing where that deeper content should live, our roundup of code documentation tools covers the options, and the how to write documentation guide goes deeper on structure once you outgrow a single file.
Frequently asked questions
What should a README include?
At minimum, a README should include a project title, a one-line description, installation instructions, and a usage example. Most projects also add configuration details, contributing guidelines, and a license. Add badges and screenshots when they help. Skip sections that do not apply rather than padding the file.
How long should a README be?
Long enough to answer what the project is, how to install it, and how to use it, and no longer. A small library might need 40 lines; a larger tool might need a few hundred. If it grows past a comfortable single scroll, move the deeper material to a dedicated docs site and keep the README as a summary.
What format is a README written in?
Almost always Markdown, saved as README.md. Markdown is a lightweight syntax that code hosts render automatically into formatted pages with headings, lists, links, and code blocks. Some older projects use plain text or reStructuredText, but Markdown is the standard on GitHub, GitLab, and Bitbucket today.
Where should the README file go?
In the top-level directory of your project, next to your source code. Code hosting services look there and display the rendered file on the repository's main page automatically. A README placed in a subfolder will not show on the project landing page, so keep the primary one at the root.
Is it okay to use AI to write a README?
Yes, as long as you check the result. AI is good at producing the structure and filling in boilerplate sections, which saves time on the parts that look the same across projects. You still need to verify the install commands, usage examples, and configuration are accurate for your actual code before you commit.