139 lines
5.1 KiB
Markdown
139 lines
5.1 KiB
Markdown
# Writing READMEs and guides
|
|
|
|
House style for Markdown in Levkin repos. Goal: docs that read like a
|
|
competent human wrote them for another engineer, not like a product page
|
|
or a chatbot reply.
|
|
|
|
Agents: also follow `~/.cursor/rules/docs-writing.mdc` and the humanizer
|
|
skill when rewriting prose.
|
|
|
|
## What belongs where
|
|
|
|
| Doc | Job |
|
|
|-----|-----|
|
|
| `README.md` | What it is, how to run it, where config and deeper docs live |
|
|
| `docs/guides/*.md` | How-to for one task (deploy, upgrade, recover) |
|
|
| `docs/reference/*.md` | Stable facts (URLs, ports, schema, CLI flags) |
|
|
| `AGENTS.md` / `.cursorrules` | Short orientation for agents, not a second README |
|
|
| `CHANGELOG.md` | What changed, by version |
|
|
| Scratch (`*_PLAN`, `*_SUMMARY`, `FIX_*`, `HANDOFF`, `PROGRESS_*`) | Temporary. Archive or delete when done; do not polish as product docs |
|
|
|
|
Do not paste the same wall of text into README and three guides. Link once.
|
|
|
|
## README checklist
|
|
|
|
Every repo README should answer these, in roughly this order:
|
|
|
|
1. **What** — one or two plain sentences. Name the audience if it is not obvious.
|
|
2. **Status** — active, beta, archived, research-only. Put archived status in a blockquote at the top.
|
|
3. **Run it** — install or `make` entrypoint and one command that works.
|
|
4. **Config** — `.env.example`, Infisical path (`/apps/<repo>`), or vault keys. Never real secrets.
|
|
5. **Pointers** — links to guides; do not duplicate them.
|
|
6. **License** — or say the repo is private / personal.
|
|
|
|
Add when useful: short architecture sketch, known limits, deploy note
|
|
("ops runbooks live in the ansible repo").
|
|
|
|
Skip in READMEs: emoji decoration, marketing feature walls, welcome blurbs,
|
|
kanban ceremony, and change-narration ("this was added to replace…").
|
|
|
|
## Guide checklist
|
|
|
|
A how-to guide should:
|
|
|
|
1. State the goal in the first sentence ("Deploy X on LXC Y").
|
|
2. List prerequisites (access, packages, secrets location).
|
|
3. Give ordered steps with copy-pasteable commands.
|
|
4. End with a verify step and what "done" looks like.
|
|
5. Link related runbooks instead of restating them.
|
|
|
|
One job per guide. Split if you need more than one primary verb.
|
|
|
|
## Voice and formatting
|
|
|
|
### Do
|
|
|
|
- Write in sentence case for headings: `## Getting started`, not `## Getting Started`.
|
|
- Prefer short paragraphs and concrete nouns (paths, hosts, commands).
|
|
- Use tables for env vars, ports, and host inventories.
|
|
- Use fenced code blocks with a language tag when it helps.
|
|
- Prefer `is` / `has` / `runs` over `serves as` / `boasts` / `features`.
|
|
- Keep bold for rare emphasis (a warning, a path). Not for every label.
|
|
|
|
### Do not
|
|
|
|
- Decorate headings or bullets with emoji (`🚀`, `✅`, `💡`, …). If a CLI
|
|
prints emoji, quote that output in a code block; do not restyle the doc around it.
|
|
- Use bold-colon list items as fake headings:
|
|
`- **Web-Based**: Modern React frontend…` → write a normal sentence or table.
|
|
- Stuff feature lists with adjectives: *state-of-the-art*, *seamless*,
|
|
*robust*, *powerful*, *comprehensive*, *cutting-edge*, *production-ready*,
|
|
*unlock*, *leverage*, *delve*, *landscape*, *tapestry*, *testament*.
|
|
- Open with chatbot filler: "Welcome to…", "Here's what you need to know",
|
|
"Let's dive in", "It is important to note that…".
|
|
- Overuse em dashes. Prefer a period, comma, colon, or parentheses.
|
|
- Title-Case Every Heading Like A Brochure.
|
|
- Invent facts, URLs, version numbers, or "experts say" attributions while editing.
|
|
|
|
### Examples
|
|
|
|
Bad:
|
|
|
|
```markdown
|
|
# 🚀 PunimTag
|
|
|
|
**Modern Photo Management and Facial Recognition System**
|
|
|
|
A fast, simple, and modern web application using state-of-the-art DeepFace AI.
|
|
|
|
## Key Features
|
|
|
|
- **Web-Based**: Modern React frontend with FastAPI backend
|
|
- **Privacy-First**: All data stored locally, no cloud dependencies
|
|
```
|
|
|
|
Good:
|
|
|
|
```markdown
|
|
# PunimTag
|
|
|
|
Local photo library with face recognition (DeepFace / ArcFace). Admin UI
|
|
(React) and viewer (Next.js) share one monorepo and a PostgreSQL backend.
|
|
|
|
## Features
|
|
|
|
- Face detect and match with RetinaFace + ArcFace (or other listed models)
|
|
- Search by person, date, tag, or folder
|
|
- Runs on your machine; no cloud dependency for core data
|
|
```
|
|
|
|
## Public vs private repos
|
|
|
|
Public READMEs and guides:
|
|
|
|
- No LAN IPs, no `10.0.10.x`, no root SSH one-liners.
|
|
- No absolute home paths (`/Users/…`).
|
|
- No other people's PII.
|
|
|
|
Private homelab docs (ansible, hermes, levkin) may name hosts and IPs.
|
|
Still skip emoji and marketing tone.
|
|
|
|
Repos under `Gitilia/*` are push mirrors from Gitea. After merging a release or
|
|
public README/docs change, sync and verify from the ansible repo:
|
|
`make github-mirror-sync` then `make github-mirror-health` (see
|
|
`ansible/docs/guides/github-mirrors.md`).
|
|
## When rewriting existing docs
|
|
|
|
1. Preserve every real fact (commands, paths, versions, URLs).
|
|
2. Cut fluff; keep the procedure.
|
|
3. Fix formatting to match this guide in the same pass.
|
|
4. Leave code blocks, frontmatter, and link targets intact unless the link is wrong.
|
|
5. Scratch/status files: delete or move under `docs/archive/` rather than
|
|
"humanizing" a dead plan.
|
|
|
|
## Related
|
|
|
|
- Project skeleton: this repo's root `README.md`
|
|
- Hard gates (CI, secrets, LICENSE): `~/.cursor/rules/new-project-standards.mdc`
|
|
- Tone scrub: Cursor skill `humanizer`
|