Software documentation template: README format with an example

When to use it

• A new repository that needs a README before anyone else clones it
• An internal tool or service that colleagues keep asking you how to run
• An open-source library or command-line tool whose README is its front page on GitHub, GitLab or npm
• Handing a project over to a new maintainer or another team

How to use this template

1. Write the one-line description first

   It sits directly under the project name and says what the project does in under 120 characters, the limit the Standard Readme specification sets for its short description. Reuse the same line as the repository and package description so the three never disagree. If the sentence will not come, the project's scope is unclear, and that is worth knowing before you write the rest.

2. Test every command on a clean machine

   Run the installation steps in a fresh container, a new user account or a colleague's laptop, and copy the commands from the terminal rather than from memory. Under each one, show what success looks like: the version number it prints or the line it ends with.

3. Keep one working example

   The quick start is the smallest thing that works end to end. Longer examples, edge cases and the full option list go in a docs folder, linked from the Documentation section.

4. Cut what does not apply, then save it as README.md

   A placeholder left in a README tells readers nobody looked. Delete the sections the project does not need, put the file in the repository root, and use relative links such as docs/tutorial.md. GitHub resolves those on every branch, while absolute links may break in a clone.

What goes in the README, and what goes elsewhere

GitHub's own guidance lists five things a README usually covers: what the project does, why it is useful, how to get started, where to get help, and who maintains it. The rest has a better home in separate files. GitHub recognizes several of them by name. A CONTRIBUTING.md, for example, is linked whenever someone opens an issue or a pull request.

For the docs folder, the Diátaxis framework by Daniele Procida is a practical map. It sorts documentation by what the reader needs: tutorials teach a newcomer through a first project, how-to guides take a competent user through one task, reference states the facts (every command, option and error), and explanation covers the why. The template's Documentation section has a line for each of the first three. Explanation can come later, or live in your decision records. When the docs grow into a full manual with architecture and troubleshooting, the technical documentation template covers that layer, and the release notes template works as a changelog format.

A filled-in example

Here is the template filled in for a small command-line tool. The project is invented. Every command can be pasted as it is, and the quick start shows the output, so a reader knows whether it worked.

# quillcheck

Checks Markdown manuscripts for broken links, missing images and duplicate headings.

- Status: active
- Latest release: 1.4.2, 2026-09-30
- Runs on: macOS, Windows, Linux
- License: MIT
- Maintainers: Ana Ruiz

## Overview

Long Markdown projects break quietly: a chapter gets renamed and three links point nowhere. quillcheck reads every .md file in a folder and reports each problem with its file and line number. It works offline and never changes your files.

- Finds links to files and headings that no longer exist
- Flags images whose files are missing
- Exits with code 1 when it finds a problem, so it can fail a CI job

## Requirements

- Node.js 20 or later

## Installation

```sh
npm install --global quillcheck
quillcheck --version
```

The second command prints the version, for example 1.4.2.

## Quick start

```sh
quillcheck ./manuscript
```

```text
chapters/03-harbor.md:41   link to #the-storm: no such heading
chapters/01-arrival.md:12  image images/map.png: file not found
2 problems in 18 files
```

## Configuration

| Setting | Default | What it does |
| --- | --- | --- |
| --ignore <glob> | none | Skips matching files |
| --external | off | Also checks web links (needs a connection) |

## Documentation

- [Tutorial: check your first project](docs/tutorial.md)
- [How to run quillcheck in CI](docs/how-to/ci.md)
- [Command reference](docs/reference.md)
- [Changelog](CHANGELOG.md)

## Getting help

Ask questions in Discussions. Report bugs as issues with your version, the command you ran and the full output. Report security problems privately, as described in [SECURITY.md](SECURITY.md).

## Contributing

Pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) explains the setup, and npm test runs the suite.

## License

MIT © 2026 Ana Ruiz

What a good README does

• Lead with use, not history. Why you started the project can wait until the end, or move to the docs. The first screen answers two questions: what is this, and how do I try it.
• State the status plainly. If the project is unmaintained or replaced, say so in the first lines, as the Make a README guide recommends, so nobody builds on it by mistake.
• Name the license precisely. Use its SPDX identifier (MIT, Apache-2.0, GPL-3.0-or-later) and keep the full text in LICENSE. As choosealicense.com explains, code with no license is under exclusive copyright by default: people can read it but have no permission to use, change or share it.
• Keep headings scannable. GitHub builds an outline menu from a README's headings, and the Standard Readme spec asks for a table of contents once a README passes 100 lines.
• Use one name for each thing. "Config file" or "settings file", not both. If several people write the docs, record those choices in a short style guide.