How to Write a README That People Actually Read

A good README answers three questions in under 30 seconds: what is this project, how do I install and use it, and where do I get help if something breaks. If a developer lands on your repo and cannot answer those questions by scanning the page, they will leave. That’s not a guess. Watch how you evaluate repos yourself.

The README is your project’s front door. It’s the first thing GitHub shows. It’s what decides whether someone stars your repo, opens an issue, or closes the tab.

The Essential Sections

Every README needs these sections, in roughly this order.

1. Project name and one-line description

State what the project does in a single sentence. Not what it “aims to be” or what it “strives to achieve.” What it does, right now.

# MDtoLink

Publish markdown files to shareable URLs with one command.

That’s it. One line. If you can’t describe your project in one sentence, the project might have a scope problem.

2. Installation

Show the exact commands to install your project. Copy-paste ready, no guessing.

## Installation

npm install -g mdtolink

If there are prerequisites (Node.js version, system dependencies, API keys), list them before the install command. Don’t make people discover them through error messages.

3. Quick start

The fastest path from zero to working. Three to five commands, max.

## Quick Start

# Publish a file
mdtolink publish README.md

# The CLI returns a URL like:
# https://mdtolink.com/d/abc123

This section should work. Test it yourself on a clean machine. Outdated quick start examples are worse than no quick start at all.

4. Usage examples

Show common use cases with real commands and realistic output. Cover the two or three things most people will actually do with your project.

## Usage

# Publish with a custom slug
mdtolink publish notes.md --slug my-notes

# Update an existing document
mdtolink publish notes.md --slug my-notes

# List your published documents
mdtolink list

5. Configuration / API

If your project has configuration options or an API, document them. A table works well for CLI flags and environment variables.

## Configuration

| Flag | Description | Default |
|------|-------------|---------|
| `--slug` | Custom URL slug | auto-generated |
| `--private` | Require auth to view | `false` |
| `--format` | Output format | `html` |

6. Contributing

Tell people how to contribute. Even a short section is better than nothing.

## Contributing

Pull requests welcome. Please open an issue first to discuss
what you'd like to change.

1. Fork the repo
2. Create your branch (`git checkout -b fix/typo`)
3. Commit your changes
4. Push and open a PR

7. License

State the license. One line is enough.

## License

MIT

Common Mistakes

These are the patterns that make developers close the tab.

Walls of text. Long paragraphs with no headings, no code blocks, no visual breaks. READMEs are scanned, not read. Break things up.

No install instructions. “You know how to install things” is not documentation. Spell it out.

Outdated examples. The quick start throws an error because the API changed six months ago. Run your own examples before you push.

Too many badges. A few badges (build status, npm version, license) are useful. Fifteen badges stacked in a row are noise. Pick three or four that matter.

Feature list instead of usage examples. “Supports X, Y, Z” tells me nothing about how to use X, Y, or Z. Show me the commands.

Giant table of contents. If your README needs a 20-line table of contents, your README is too long. Move detailed docs to a /docs folder or a documentation site.

Formatting Tips

Small formatting choices make a big difference in readability.

Short paragraphs. Two to three sentences, max. White space helps scanning.

Fenced code blocks with language hints. Always specify the language for syntax highlighting.

```bash
npm install -g mdtolink
```

Badges for project status. Put them right after the project title.

# MDtoLink

![npm version](https://img.shields.io/npm/v/mdtolink)
![license](https://img.shields.io/github/license/user/mdtolink)

Use headers as anchor links. People share links to specific README sections. Make your headers descriptive so the auto-generated anchors make sense.

Copy-Paste README Template

Here’s a starter template. Delete what you don’t need.

# Project Name

One-line description of what this project does.

![build](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)
![npm](https://img.shields.io/npm/v/package-name)
![license](https://img.shields.io/github/license/user/repo)

## Installation

```bash
npm install package-name
```

## Quick Start

```bash
package-name init
package-name run
```

## Usage

```bash
# Common use case 1
package-name do-thing --flag value

# Common use case 2
package-name other-thing
```

## Configuration

| Option | Description | Default |
|--------|-------------|---------|
| `--flag` | What it does | `value` |

## Contributing

PRs welcome. Open an issue first to discuss changes.

## License

MIT

Sharing Your README Beyond GitHub

Your README lives on GitHub, but sometimes you need to share it outside that context: in a Slack channel, an email, a project proposal, or a client-facing page.

You can publish your README to a shareable URL with MDtoLink. The published version renders the markdown with proper formatting, syntax highlighting, and a clean layout. Anyone with the link can read it, no GitHub account required.

mdtolink publish README.md --slug my-project-readme

That gives you a URL you can drop anywhere. When you update the README and re-publish, the same URL shows the latest version.

The Rule of 30 Seconds

After writing your README, open it in a browser and time yourself. Can you answer “what, how, and where” in 30 seconds? If not, cut and restructure until you can. Your README is not a novel. It’s a reference card. Treat it that way.