Conventional readme

Conventional README Skill

Create and maintain a clear, comprehensive README.md following the conventions from Make a README.

File

Name it README.md at the project root. Use Markdown.

Template

# Project Name

One-paragraph description of what the project does and why it exists.
Link to any reference the reader might be unfamiliar with.

## Installation

Step-by-step instructions to install the project.

## Usage

Examples showing how to use the project. Show expected output.

## Contributing

How others can contribute. Link to CONTRIBUTING.md if it exists.

## License

State the license. Link to the license file or choosealicense.com.

Section Guidelines

Name

Use a self-explaining project name as the H1. Do not repeat "README" in the title.

Description

• One paragraph — what the project does, who it's for, and why it's useful.
• Link to any external concepts the reader might not know.
• Mention key differentiators if alternatives exist.
• Optional subsections: ### Features, ### Background, ### Comparison with alternatives.

Badges

Add badges for build status, version, license, and coverage using Shields.io. Place them directly below the description, before the first content section. Common badges:

![Build Status](https://img.shields.io/github/actions/workflow/status/OWNER/REPO/ci.yml)
![Version](https://img.shields.io/github/v/release/OWNER/REPO)
![License](https://img.shields.io/github/license/OWNER/REPO)

Do not over-badge. Limit to 4-5 meaningful badges.

Installation

• Provide the exact command for the most common package manager.
• Include a ### Requirements subsection if there are prerequisites (OS, language version, dependencies).
• For novices, write out steps explicitly rather than assuming ecosystem knowledge.
• If the project is a library, show the install command. If it's an app, show how to clone, build, and run.

## Installation

### Requirements

- Python 3.10+
- PostgreSQL 14+

### Using pip

\```bash
pip install mypackage
\```

### From source

\```bash
git clone https://github.com/OWNER/REPO.git
cd REPO
pip install -e .
\```

Usage

• Show, don't just tell — include code examples with expected output.
• Start with the smallest useful example (the "hello world" of your project).
• Link to more comprehensive examples or docs if the full usage is too long.
• Use fenced code blocks with the appropriate language tag for syntax highlighting.

## Usage

\```python
from mypackage import Client

client = Client(api_key="your-key")
result = client.do_something("input")
print(result)  # => "expected output"
\```

For advanced usage, see [the docs](./docs/usage.md).

Support

Tell people where to get help:

## Support

- [Issue Tracker](https://github.com/OWNER/REPO/issues) — for bugs and feature requests
- [Discussions](https://github.com/OWNER/REPO/discussions) — for questions and ideas
- [Email](mailto:[email protected]) — for security vulnerabilities

Roadmap

Optional. List planned features or link to a project board. Only include if there are concrete plans.

Contributing

State whether contributions are accepted and how to get started. If there is a CONTRIBUTING.md file, link to it rather than duplicating content.

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

If there is no separate contributing file, include:

• How to set up the dev environment
• How to run tests
• How to submit changes (branch naming, PR process)

Authors and Acknowledgment

Show appreciation to contributors. Can be a simple line or a dedicated section.

License

State the license clearly and link to it:

## License

[MIT](./LICENSE)

For projects without a license file, recommend adding one via choosealicense.com.

Project Status

Optional. If the project is unmaintained, experimental, or archived, say so prominently at the top of the README.

> **Note:** This project is no longer actively maintained. Pull requests are still accepted.

Writing Style Rules

1. Too long is better than too short — a detailed README is always preferred over a sparse one.
2. Use active voice — "Install the package" not "The package can be installed".
3. Address the reader directly — "you" and "your".
4. Code blocks for all commands — never leave commands as inline code only.
5. Show expected output — helps users verify they're doing it right.
6. One concept per section — if a section is getting long, split it into subsections.
7. Link, don't duplicate — if documentation exists elsewhere, link to it.

Anti-Patterns — Never Do These

Anti-Pattern	Why It's Bad	Do This Instead
No README at all	New users have no starting point	Create one before sharing the project publicly
Vague description	"A tool for things" tells no one anything	Be specific: what it does, for whom, why it's useful
No installation steps	Users guess how to get started	Show the exact command(s)
No usage examples	Users read code to learn how to use it	Show at least one minimal working example
Wall of text, no code	Hard to scan, intimidating	Break up text with code blocks, lists, and headings
Outdated README	Instructions no longer work	Update README when changing install/usage steps
Missing license	Legal ambiguity for users	Always include a license section
"Coming soon" without links	Dead end, no way to follow progress	Link to issues, milestones, or a roadmap
README as the only docs	README becomes impossibly long	Link to a docs site, wiki, or additional markdown files

When the README Is Too Long

If the README grows beyond ~300 lines, consider splitting content:

• docs/ directory or a documentation website (Docusaurus, MkDocs, Docsify)
• CONTRIBUTING.md — move contributing guidelines out
• SECURITY.md — move security/vulnerability reporting out
• ARCHITECTURE.md — move technical architecture decisions out

The README should remain the entry point: overview, install, usage, and links to everything else.

Example (Complete)

# Foobar

Foobar is a Python library for dealing with word pluralization.

![Build Status](https://img.shields.io/github/actions/workflow/status/acme/foobar/ci.yml)
![Version](https://img.shields.io/pypi/v/foobar)
![License](https://img.shields.io/github/license/acme/foobar)

## Installation

Use the package manager [pip](https://pip.pypa.io/en/stable/) to install foobar.

```bash
pip install foobar

Usage

import foobar

# returns 'words'
foobar.pluralize('word')

# returns 'geese'
foobar.pluralize('goose')

# returns 'phenomenon'
foobar.singularize('phenomena')

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT