How to Write a Good README (With a Copy-Paste Template)

The README is the front page of your project. It is the first thing people see on GitHub, the first file a new teammate opens, and often the only documentation a small project has. A good one answers three questions in under a minute: What is this? Should I care? How do I get it running?

This guide covers what to include, in the order readers look for it, and ends with a template you can copy.

Who reads your README?

Different readers want different things, usually in this order:

1. Evaluators decide in seconds whether the project solves their problem. They read the title, the first paragraph and maybe a screenshot.
2. New users want to install and try it. They jump to the quick start.
3. Regular users come back for configuration options and examples.
4. Contributors need to set up a development environment and know the rules.

Structure the README so each group finds its part quickly, with the evaluator's information at the top.

The essential sections

1. Title and one-sentence summary

Say what the project does and for whom, in plain words:

# cronwhy

Explain cron expressions in plain English and list their next run times — from the command line.

Avoid opening with history, motivation essays or a list of badges. Those can come later or not at all.

2. A visual, if it helps

For anything with a UI or terminal output, a screenshot or short GIF shows more than a paragraph. Keep it near the top and keep the file small.

3. Quick start

The fastest path from zero to "it works". Copy-pasteable commands, in order, with the expected result:

## Quick start

```bash
pip install cronwhy
cronwhy "0 9 * * 1-5"
```

Output:

```text
At 09:00 on Monday through Friday (UTC).
Next: Thu 2026-10-29 09:00, Fri 2026-10-30 09:00, Mon 2026-11-02 09:00
```

List prerequisites first (language version, tools) if they are not obvious. Test the quick start on a clean machine or container — missing steps here lose more users than anything else.

4. Usage and examples

Show the most common tasks with real examples rather than describing every option in prose. Three good examples beat a wall of flags.

5. Configuration

A table works well for options and environment variables:

| Variable | Default | Description |
|---|---|---|
| `PORT` | `8000` | Port the server listens on |
| `DATABASE_URL` | `sqlite:///app.db` | Database connection string |
| `LOG_LEVEL` | `info` | One of debug, info, warning, error |

Mention where secrets go and never include real credentials. See how to use .env files safely.

6. Development setup

How to clone, install dependencies, run tests and run the project locally. If you have a Makefile, this section can be very short — see Makefiles for modern projects:

## Development

```bash
git clone https://github.com/you/cronwhy.git
cd cronwhy
make install
make test
```

7. Contributing

For open-source projects: how to report bugs, how to propose changes, code style, and whether to open an issue before a pull request. Longer guidelines belong in a separate CONTRIBUTING.md that the README links to.

8. License

One line naming the license, with a link to the LICENSE file. Without a license, others legally cannot reuse your code, even if it is public.

Optional sections that earn their place

• Features: a short bullet list, if the summary cannot cover them.
• FAQ / troubleshooting: the questions you keep answering in issues.
• Roadmap or status: especially if the project is experimental or unmaintained. Saying "This project is no longer maintained" up front saves everyone time.
• Badges: build status and latest version are useful; a dozen decorative badges are noise.
• Acknowledgements: credit projects or people you built on.

Writing tips

• Lead with the outcome, not the implementation. "Deploy static sites with one command" beats "A Go CLI wrapping the X API".
• Use headings so readers can scan and GitHub generates a table of contents.
• Keep commands copy-pasteable: no $ prompts inside code blocks, no placeholder text people will paste by accident without noticing.
• Show expected output after commands so users know they succeeded.
• Link instead of duplicating: move long reference material to a docs/ folder or a docs site.
• Keep it current: update the README in the same pull request that changes behavior. An outdated quick start is worse than none.

README for internal or work projects

Internal projects need READMEs too — arguably more, because the people asking questions might leave. Add:

• Owners: the team or channel responsible.
• Architecture overview: a few sentences or a diagram showing how pieces connect.
• Environments: where staging and production run, and how to deploy.
• Runbook links: what to do when it breaks.

Copy-paste template

# Project Name

One sentence: what it does and who it is for.

![Screenshot](docs/screenshot.png)

## Quick start

Prerequisites: Python 3.12+ (or Node 20+, Docker…)

```bash
# install
# run
```

Expected output:

```text
…
```

## Usage

### Common task 1

```bash
example command
```

### Common task 2

```bash
example command
```

## Configuration

| Variable | Default | Description |
|---|---|---|
| `EXAMPLE` | `value` | What it does |

## Development

```bash
git clone …
make install
make test
```

## Contributing

Bug reports and pull requests are welcome. Please open an issue first to discuss larger changes. See CONTRIBUTING.md.

## License

MIT — see LICENSE.

FAQ

How long should a README be?

As short as possible while covering the quick start, usage and configuration. Small libraries may need one screen; larger tools should keep the README focused and link to full docs.

Should the README be in Markdown?

On GitHub, GitLab and most other platforms, yes. README.md is rendered automatically on the repository's front page.

Can AI write my README?

An AI assistant can produce a good first draft from your code and commands. Always run the quick start yourself and correct anything it guessed — see how to write better prompts for AI coding assistants.

Further reading

• GitHub Docs: About READMEs
• Choose a License
• Related: 25 Git commands every developer should know