readme-writing
verified73f16f87-8039-4315-b5ac-97d11d4ec09c
Write a production-quality README — what it does, quickstart, usage, config, and contributing — that gets a new user running in minutes. Use when a project lacks a README or its README is stale.
Metadata
Skill file
# README Writing
Use when creating or refreshing a project README — your goal is to get a new user from zero to running code in under 5 minutes.
## The README Skeleton
```markdown
# Project Name
> One-liner: what it does and who it's for.
[](https://pypi.org/project/project/)
[](https://github.com/user/project/actions)
[](LICENSE)
## What It Does
2–3 sentences. No jargon. A newcomer should understand the value proposition.
## Quickstart
```bash
# Copy-paste these commands. They must work.
pip install myproject
myproject init
myproject serve
# Open http://localhost:8080
```
## Usage
### Basic Example
```python
from myproject import Client
client = Client()
result = client.do_thing("input")
print(result)
```
### Common Patterns
...2–3 more examples covering the main workflows...
## Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
| `DATABASE_URL` | Yes | — | Postgres connection string |
| `PORT` | No | `8080` | HTTP listen port |
| `LOG_LEVEL` | No | `info` | One of: debug, info, warn, error |
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines.
## License
MIT — see [LICENSE](LICENSE) for details.
```
## Making the Quickstart Actually Work
**The golden rule**: Every command in the README must have been executed by you, in a clean environment, immediately before publishing.
```bash
# Test in a clean venv
python -m venv /tmp/test-readme
source /tmp/test-readme/bin/activate
# Now copy-paste each command from the README exactly as written
pip install myproject
myproject init # Does this work? Missing deps? Wrong flag?
myproject serve # Does it start?
# Deactivate and clean up
deactivate
rm -rf /tmp/test-readme
```
## Badge Selection
| What | Badge Source |
|---|---|
| Package version | shields.io → PyPI / npm / crates.io |
| CI status | GitHub Actions / CircleCI native badge |
| Coverage | Codecov / Coveralls |
| Docs | Read the Docs |
| License | shields.io |
**Rule**: Only include badges for services that are actually set up. A broken/fake badge is worse than no badge.
## Keeping It Truthful
- **The one-liner must match what the code actually does today**, not the roadmap.
- **Config table must list every required env var** — nothing is "obvious."
- **If a feature is experimental or broken**, say so or omit it from the README.
- **The quickstart should use the published package**, not `pip install -e .` (that's for contributors).
## README Sections by Project Type
| Project type | Essential sections |
|---|---|
| Library / SDK | Install, Quickstart, API reference, Config, License |
| CLI tool | Install, Quickstart (3 commands), Usage + flags table, Examples |
| Web service | Quickstart (run locally), Config/env table, API endpoints, Deploy |
| Data / analysis repo | Setup, Data description, How to reproduce results, Outputs |
| Internal tool | Purpose, Quickstart, Who to ask, Links to docs |
Don't include every section for every project. A library doesn't need "Deploy"; a CLI tool doesn't need "Data description."
## The Quickstart Quality Bar
A good quickstart meets these three tests:
```bash
# Test 1: Does a fresh environment work?
docker run -it --rm python:3.11-slim bash -c "pip install myproject && myproject --help"
# → should print usage, not an ImportError
# Test 2: Are the commands in the right order?
# Install → configure → run. A step that references an unset env var
# or a file created by a later step is a broken order.
# Test 3: Is the "happy path" actually happy?
# The quickstart should demo the ONE most common use case,
# not the most complex one.
```
## Common Section Reference
| Section | What goes in it |
|---|---|
| **What It Does** | 2–3 sentences + a "why it exists" |
| **Quickstart** | Copy-paste-runnable, <10 lines, happy path |
| **Usage** | 2–3 worked examples, real input → real output |
| **Configuration** | Env var table: name, required, default, description |
| **Contributing** | Link to CONTRIBUTING.md + setup for devs |
| **FAQ** | Real questions users ask, not invented ones |
| **License** | License type + link |
## Guardrails
- **Never** publish a README with untested commands. Run every one yourself in a clean environment.
- **Never** claim features that don't exist yet ("coming soon" is acceptable, "supports X" when it doesn't is not).
- **Never** list config/env vars that aren't actually read by the code.
- **Always** include a license. Without it, nobody can legally use your code.
## Pitfalls
- **Documenting intent, not reality**: The README describes what you *want* the project to be, not what it actually is. When in doubt, open the code and verify.
- **Examples that were never executed**: Typos in flag names, wrong import paths, missing setup steps. A copy-paste from the README must succeed.
- **Wall of text before the quickstart**: Users scan. The quickstart must be visible above the fold (no scrolling). Details below.
- **No "Why" section**: A README that lists features but never says *why this project exists* fails to convert skimmers into users.
- **Forgetting to update the README after CLI changes**: The README is part of the release checklist. If you change the CLI flags, change the README.
## Verify / Checklist
- [ ] Quickstart commands tested in a clean environment (fresh venv/container)
- [ ] Every config/env var in the table is actually used by the code
- [ ] One-liner accurately describes what the project does today
- [ ] Badges are live and reflect current state (not broken images)
- [ ] License file exists and license badge matches
- [ ] README renders correctly on GitHub/GitLab (check the preview)
- [ ] All links (docs, contributing, homepage) are valid
- [ ] Table of contents included if README is >3 scrollsAttached files
No attached files.