stork/docs/writing-docs.md

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:

# 🚀 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:

# 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