How to Write a Good README for Your Project

Someone clones your project, opens the repository, and tries to run it. The README says “Install dependencies and start the app.” Which dependencies? Which command? What does “start” mean? After ten minutes of guessing, the visitor closes the tab. The code may be excellent, but the project never got a fair first test.

A good README is not a decorative summary placed beside a repository. It is an onboarding path. It should help a reader understand what the project does, decide whether it is relevant, get a working copy, find help, and know what they are allowed to do with the code. GitHub’s documentation describes those purposes directly and notes that a repository README is often the first item a visitor sees in its guide to README files.

Before: a README that describes the author’s memory

# Task Tracker

A simple task app built with Python.

## Run it

Install the requirements and start the application.

## Features

- Tasks
- Users
- Reports

This README is not empty, but it forces the reader to fill in the most important gaps. Which Python version? Which command installs requirements? Is a database needed? Is there a demo account? Do “users” and “reports” already work, or are they planned? The author can answer each question because the author already knows the project. A new contributor cannot.

The fix is not adding every thought the author has ever had. The fix is making the reader’s next decision explicit. A README should reduce uncertainty in the order a new person encounters it.

After: the README behaves like a tested path

# Task Tracker

A command-line task tracker for practicing Python file handling and tests.

## Quick Start

### Requirements

- Python 3.12 or newer
- Git

### Setup

```bash
git clone https://github.com/example/task-tracker.git
cd task-tracker
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### Run

```bash
python -m task_tracker
```

The app opens an interactive terminal menu where you can add, complete,
and list tasks.

The second version makes a promise the first one avoided: a reader with a stated environment can follow a sequence. It also exposes assumptions. If the project requires a database, environment variables, or a different activation command on Windows, those details must appear rather than being left for an error message to reveal.

Our guides to creating a GitHub repository and setting up a coding environment provide useful background. The README should not repeat every beginner lesson; it should link to the project-specific information a reader needs next.

Give the project a sentence a stranger can test

A title identifies the project. The sentence below it explains why the project exists. “A Python app” is a technology label, not a useful description. “A command-line task tracker for practicing Python file handling and tests” tells the reader what it does, how it is used, and why it may be relevant.

Use a description that could be challenged. If the sentence says the project supports reports, a reader should be able to find the report command or a clearly marked limitation. Avoid claiming features that are only planned. A README becomes less trustworthy each time its description gets ahead of the code.

Make Quick Start executable, not inspirational

Installation instructions are the part most likely to fail when written from memory. Write the commands in the order a fresh reader needs them, then run those commands in a clean directory or disposable environment. A setup sequence should answer five questions:

1. What tools and versions must already be installed?
2. How does the reader obtain the source?
3. How are dependencies installed?
4. Which configuration values are required?
5. What exact command proves the project is running?

Do not hide a required environment variable inside a sentence such as “configure your API key.” Show a safe placeholder and explain where the value comes from. Never publish a real key in a README, example, screenshot, issue, or commit. The Vandutz article on environment variables and `.env` files covers the separation between configuration and secrets; your README should tell readers how to create local configuration without revealing yours.

# .env.example
API_BASE_URL=https://api.example.com
API_KEY=replace-with-your-local-key

Then explain that `.env` is local and ignored, while `.env.example` is safe documentation. Confirm that the ignore rule is committed and that the example contains no credential that could authenticate to a real service.

Use Markdown to expose structure

A README does not need elaborate design. GitHub supports headings, emphasis, inline code, fenced code blocks, links, lists, tables, and relative paths through GitHub Flavored Markdown. Its official formatting guide confirms that headings create hierarchy and that three backticks create a distinct code block in the Markdown syntax documentation.

Use headings for questions a reader is likely to ask, not for vague stages such as “More Information.” Use inline code for filenames, commands, and symbols. Use fenced blocks for commands that should be copied. Keep prose outside the code block so a reader understands what the command is expected to do before running it.

GitHub also generates an outline from headings in a rendered Markdown file and creates anchors for sections. That means a long README can remain navigable without a manually maintained table of contents. If you add a manual list, test every anchor after editing headings; changing a heading changes the generated link target.

Show the result before explaining the machinery

A command-line project can show a terminal session. A web project can show a screenshot or a small interaction. An API client can show a request and a sanitized response. A visual preview answers the reader’s first practical question faster than a paragraph claiming that the project is “easy to use.”

$ python -m task_tracker
Task Tracker
1. Add task
2. Complete task
3. List tasks

> 1
Task title: Read the README
Saved task #1

Use screenshots and animated images carefully. They should show a real state of the project, not a mockup that the current code cannot reproduce. If the image contains personal data, tokens, local paths, or customer information, replace it before committing.

Explain the smallest useful architecture

A reader does not need a dissertation before running the project. They do need a map when the repository contains several directories. A short section can connect folders to responsibilities:

task_tracker/
├── cli.py          # terminal menu and user input
├── storage.py      # reading and writing task data
└── models.py       # task data structure

tests/
└── test_storage.py # storage behavior

Keep the map honest. If a folder is generated, ignored, or optional, say so. If a command must be run from the repository root, show that in the setup instructions. If detailed API documentation or contribution rules grow beyond the README, move them into a `docs` directory and link to them. GitHub’s README guidance makes the same distinction: a README should contain what developers need to get started and contribute, while longer material belongs in dedicated documentation or a wiki.

License is not a decoration at the bottom

A license tells readers what they may do with the code and under which conditions. Do not describe a project as “free to use” when no license has been selected. Copyright normally remains with the author unless the author grants permissions through a license, so a public repository is not automatically public-domain software.

If you are choosing a license for a small open-source project, consult a reliable license guide such as Choose a License and describe the actual file included in the repository. Do not paste a license name into the README while forgetting to commit the corresponding `LICENSE` file.

Before: secrets and stale promises

## Configuration

Set your API key here:

API_KEY=sk-live-1234567890

This is a security failure and a documentation failure. The key can be copied from the repository history even after the line is deleted, and the instruction tells every reader to treat a credential as ordinary setup text. GitHub documents push protection as a feature designed to prevent hardcoded credentials from being pushed to a repository in its security guidance, but detection is not a substitute for keeping secrets out of examples.

The second stale-README failure is quieter: the README says “run `python main.py`” after the project has moved to a package entry point. New contributors think their environment is broken, while the actual defect is that documentation was not changed with the code. Treat the README as part of the project’s interface and update it in the same change as the behavior it describes.

A template that earns its place

# Project Name

One sentence: what it does and who it helps.

## Quick Start

Requirements, clone command, dependencies, configuration, and run command.

## Usage

A real command, request, screenshot, or example output.

## Project Map

The few directories a new contributor needs to recognize.

## Tests

The exact command and what a passing run means.

## Limitations

What is incomplete, experimental, or intentionally out of scope.

## Contributing

How to propose a change and what checks are expected.

## License

The license file and the practical permissions it grants.

This template is deliberately smaller than many popular README checklists. Add a section when it answers a real question from a reader. Remove it when it only signals that the author has seen a template.

The clean-machine test

Open the repository as if you had never seen it. Use a new directory, a fresh virtual environment or package install, and only the prerequisites named in the README. Follow the setup commands exactly. Do not fill gaps from memory. Every time you have to guess, write down the missing instruction.

Then test the promised path from another perspective. Can a reader identify the project in ten seconds? Can they see what success looks like? Can they find the license and support route? Can they tell which values are safe to copy and which must be created privately? Can they distinguish implemented features from a roadmap?

Version control, package managers, environments, and CI make this test easier to repeat. Our guides to CI/CD, package managers, and Git cover the surrounding workflow. The README’s job is to connect those tools to this particular project.

Questions beginners usually ask

Write for the first ten minutes

The best README is not the one with the most sections. It is the one that lets a new reader move from “What is this?” to “I ran it” without inventing missing steps. Write the path, run the path on a clean environment, and update the path whenever the project changes.

Your repository can contain sophisticated code and still make a poor first impression. A tested README gives that code a fair chance to be understood, used, reviewed, and improved.

Put the README into a real repository with this GitHub setup guide →

Alex Carter

Alex Carter is the editorial name behind Vandutz Academy, a programming blog for beginners. Alex reviews and tests the examples and explanations published on the site, with a focus on making Python, JavaScript, web development, and developer tools easier to understand.