How to Write a Good README: Simple Guide
Introduction
A README is the first practical guide people use to understand a repository. It sits at the front door of a project and answers the questions that matter most: What is this? How do I install it? How do I use it? How do I help improve it?
On GitHub and GitLab, a strong README reduces friction for anyone opening a repository for the first time. Developers can judge whether the project solves their problem, users can get it running faster, and contributors can see how to start without guessing. A weak README creates confusion and makes support harder.
Learning how to write a good README means learning how to make a project easier to understand, install, use, and contribute to. The best READMEs are clear, scannable, concise, and specific to the project type, whether you’re documenting a library, CLI tool, web app, or open source package. They use Markdown well so readers can find the right section quickly and move from overview to action without friction.
This guide gives you a simple structure, a reusable template, and practical examples you can adapt and publish your README with confidence. If you already have a draft, you can also log in to GetPagemark and refine it as you go.
What is a README file?
A README file is a short project guide, usually written in Markdown, that explains what a repository does and how to use it. In open source projects, it is often the first place people look for installation instructions, usage examples, contributing guidelines, and license information.
A README is not a full documentation site. It is the entry point that helps readers decide whether the project is useful and what to do next.
What makes a good README?
A good README is clear, complete, brief, scannable, and useful. It answers the most common questions first: what the project does, how to install it, how to run it, and where to get help. It should also tell readers whether the project is actively maintained and where to find documentation if they need more detail.
Strong READMEs balance detail with brevity. They include enough context to be useful, but stop before turning into a wall of text. Weak READMEs are vague, outdated, or overloaded with internal notes that do not help the reader.
Markdown helps make a README easy to scan. Use headings, bullets, short paragraphs, code blocks, and whitespace so readers can find setup steps or examples fast.
What should be included in a README?
A solid README usually starts with the project name and a one-sentence description: what it does, who it is for, and why it exists. Add installation instructions with prerequisites, dependencies, setup steps, and copy-pasteable commands. Use usage examples to show the main workflow and the first successful run.
Then list a few benefit-oriented features, like “sync files automatically” or “generate reports from CSV data.” Add contributing guidelines if others can help, including branch, test, and pull request steps. Include the license so users know the legal terms for use and reuse. If the project has a documentation site, link to it from the README so readers can go deeper without searching.
A complete README often includes:
- Project name and short summary
- Features
- Installation instructions
- Usage examples
- Contributing guidelines
- License
- Documentation link
Not every README needs every section, but every project should help readers understand the project, install it, use it, and know what to do next. If you want to publish your README or log in to GetPagemark, keep this structure tight and readable.
How long should a README be?
A README should be as long as it needs to be to answer the reader’s first questions, and no longer. For a small library or CLI tool, that may mean a few short sections. For a larger application, it may mean a longer file with screenshots, tests, and links to documentation.
The right length depends on the project. If the README is too short, readers will not know how to install or use the project. If it is too long, the most important details get buried. Aim for enough detail to get started quickly, then move advanced material into documentation.
Do I need a table of contents in my README?
A table of contents is useful when the README is long enough that readers may need to jump between sections. It is especially helpful for projects with installation instructions, usage examples, tests, roadmap notes, and support details.
For short READMEs, a table of contents is optional and may add unnecessary clutter. For longer READMEs, it improves readability and helps readers find the section they need faster.
What is the best README structure?
Use a structure that moves from overview to action:
- Project name
- Short summary
- Features
- Installation instructions
- Usage examples
- Contributing guidelines
- License
- Documentation or support link
This order works well for most repositories because it answers the most common questions early. If your project is small, you can combine sections. If it is larger, add a table of contents near the top.
How do I write installation instructions?
Good installation instructions remove guesswork. Start with prerequisites such as language version, package manager, or operating system requirements. Then show the exact commands needed to install dependencies, configure the project, and start it.
For example:
git clone https://github.com/example/csv-cleaner.git
cd csv-cleaner
pip install -r requirements.txt
python app.py
If setup requires environment variables, database migrations, or a build step, include those too. Keep the commands in the same order a new user would follow them. If the project supports multiple platforms, note any differences clearly.
How do I write usage examples?
Usage examples should show the most common task a reader wants to complete. Use a real command, a short explanation, and the expected result when possible.
For example:
python app.py input.csv --dedupe --date-format ISO
Then explain what the command does in plain language. If the project has several modes, include one example for each major workflow. For libraries, show a minimal code sample. For apps, show the first successful run. For APIs, show request and response examples.
Should I include features in my README?
Yes, if the features help readers understand why the project is worth using. Keep the list short and benefit-focused. Instead of listing internal implementation details, explain what the user can do.
Good feature bullets:
- Sync files automatically
- Generate reports from CSV data
- Export results in multiple formats
If the project is still evolving, you can pair features with a roadmap so readers know what is available now and what is planned next.
What should a contributing section include?
A contributing section should tell people how to help without making them guess. Include setup steps for the development environment, how to run tests, how to open an issue, and how to submit a pull request.
A useful contributing section often covers:
- How to fork or clone the repository
- How to install dependencies
- How to run tests
- How to submit a pull request
If the project has a separate contributing guide, link to it from the README and keep the summary short.
Why is a license important in a README?
A license tells readers what they are allowed to do with the project. Without one, people may not know whether they can use, modify, or redistribute the code.
For open source projects, the README should point to the license file and name the license clearly. Common choices include the MIT License, Apache License 2.0, and GNU GPL. If the project uses a different license, say so explicitly.
What are common README mistakes?
Common mistakes include missing setup steps, outdated commands, broken links, no examples, and writing for the wrong audience. Other problems are vague project summaries and missing license information.
A README should be easy to skim and easy to trust. Before you publish your README, log in to GetPagemark and review it for accuracy.
How can I make my README more readable?
Use plain language, short paragraphs, and headings that match the reader’s questions. Break long explanations into bullets. Put the most important information near the top. Use Markdown formatting consistently so the file is easy to scan.
Other readability tips:
- Keep sentences short
- Use code blocks for commands and examples
- Add screenshots when visuals help
- Link to documentation instead of repeating long explanations
README template you can copy
# Project Name
Short summary of what the repository does, who it helps, and why it exists.
[](#)
[](#)
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)
- [Support](#support)
## Features
- Key feature 1
- Key feature 2
## Installation
```bash
# install command
Usage
# command or code example
Contributing
Support
License
This project is licensed under the MIT License.
Use this order for most repositories: title, summary, features, installation instructions, usage examples, then contributing guidelines and license. Add support or a table of contents only when they help readers. If you want to [publish your README](https://getpagemark.com) or [log in to GetPagemark](https://getpagemark.com/login), keep the same structure and fill in the placeholders with real commands and links.
## Bad vs. good README examples
**Vague:** “This project helps with data.”
**Better:** “A Python CLI for cleaning CSV files for analysts who need to remove duplicates, normalize dates, and export tidy datasets.”
**Bad installation instructions:** “Run the app.”
**Good installation instructions:**
```bash
git clone https://github.com/example/csv-cleaner.git
cd csv-cleaner
pip install -r requirements.txt
python app.py
Abstract usage: “Use the tool to process files.”
Useful usage example:
python app.py input.csv --dedupe --date-format ISO
Cluttered paragraphs hide details; strong Markdown uses headings, bullets, and code blocks so readers can scan fast. Broken GitHub links, outdated commands, and a missing license section make a README look abandoned and reduce trust.
Best practices and common mistakes
Write the README for its intended audience: a contributor needs setup and tests, while a user needs install and usage steps. Use plain language, not internal jargon, and format everything in Markdown with headings, bullets, short paragraphs, and code blocks so readers can skim fast. Keep it concise, but include enough context to trust the project.
Update the README whenever installation, usage, or project status changes. If npm install becomes pnpm install, fix it immediately; if the project is archived, say so. Include a clear license and support details such as an issue tracker so people know how the project is maintained and where to ask for help.
Common mistakes: missing setup steps, outdated commands, broken links, no examples, and writing for the wrong audience. A README should be easy to skim and easy to trust. Before you publish your README, log in to GetPagemark and review it for accuracy.
Conclusion
The core goal of a good README is simple: help someone understand the project, install it, use it, and contribute without confusion. If your README does that quickly, it is doing its job.
The best README is not the longest one. It is concise, current, and easy to scan, with the most useful details near the top and clear headings throughout. In Markdown, that usually means a short project summary, setup steps, usage examples, contribution guidance, and license information that matches the state of the repository.
Start with the template and fill in the essential sections first. Get the installation, usage, and license details right before adding extras like screenshots, badges, or a roadmap. Once those basics are complete, review the README as if you were seeing the repository for the first time.
If you want a practical next step, use the template to draft or improve your README, then publish your README. If you already have one, log in to GetPagemark and update it so it reflects the project as it exists now. That is the simplest way to turn a README into a useful entry point for your repository.
Want to try GetPagemark? Get started for free →