writing-markdown-docslisted
Install: claude install-skill SeanoChang/seanock
# Writing Markdown Docs
A document is read by someone who was not there. Every rule here serves that
reader: they get the answer first, they never meet an undefined term, and they
see a picture where prose would be a wall.
## Non-negotiables
1. **Answer first.** Open with a `> [!tldr]` of at most 60 words, or an opening
paragraph of at most three sentences. Nothing comes before it except a
one-line `Changed since <date>:` in a handoff. Method, sources and caveats go
after the answer (`lead-long`, `lead-late`).
2. **Write to the reader.** Say "you", not "the user" or "the owner". Leave out
the story of how the work was done (agents, panels, rounds) unless the reader
asked for it (`reader-third`).
3. **Define every term and ID once,** in the reader's words, where it first
appears. Prefer a name to an ID: "the retry fix", not "D128". A project's own
numbering pairs with a name on first use: "L0 normalize" (`undefined-id`).
4. **One idea per sentence.** Write about 60% of the way to ASD-STE100: active
voice and plain words. Aim for 15 to 20 words a sentence, never over 30. An
aside gets a sentence of its own (`prose-long`, `paren-dense`, `dash-dense`).
5. **Pick a representation for each idea** from the table below. A section of
more than about 250 words with no table, diagram, math or image is a wall
(`no-visual`).
6. **Fit the genre's budget, and cut.** The budget counts what the reader reads:
prose and tables. Every sentence must change w