# 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.

## 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`