# Documentation Guide

A short guide to writing clear, scannable READMEs and docs. Focus on reader flow, one source of truth, and consistent structure. Use it for any project.

---

## 1. Reader flow first

- **Who opens this, and why?** (e.g. first-time setup, finding an entry point, configuring something.)
- Order content by **what they do next**: entry points (URLs, paths), prerequisites, then steps. Not by “what we want to say.”
- Put key info (URLs, commands) where it’s easy to spot; use headings and lists so the doc is scannable.

---

## 2. Single source of truth

- State each piece of information **once**, in the place where it belongs. Elsewhere, refer (“see above”) or summarize briefly.
- **Duplication** means future edits in two places and risk of drift. Before adding a paragraph, ask: “Is this already covered?” If yes, link or condense.

---

## 3. Consistent level of abstraction

- In a given section, stay at one level: either **what** (concepts, requirements) or **how** (actions). Don’t mix long narrative with step-by-step in the same block.
- Example: Prerequisites = list of **what you need**; Steps = **what to do**, in order. Readers can tell “requirements” from “actions” at a glance.

---

## 4. Match wording to real usage

- Use terms that reflect **how people actually use** the product or feature. If something is used in articles and event pages, say so; don’t use a vaguer term like “audience.”
- Before finalizing, ask: “In what context will this be used?” Align the wording with that context.

---

## 5. Embed links in the sentence

- Attach links to the **natural phrase** in the sentence (e.g. “from a [Foo service](url)”) instead of a trailing “see [here](url).”
- The link should complete the thought; the reader shouldn’t have to jump to understand what the link is for.

---

## 6. Titles vs. body

- **Titles**: scope and navigation. Keep them short; put details in the body (e.g. “Deployment” with specifics like “Docker Compose” in a Prerequisites or Steps section).
- **Body**: the actual content. Don’t overload the heading with sub-details.

---

## 7. Use steps for sequences

- For anything **done in order**, use numbered steps (1, 2, 3). Each step = one clear action; avoid long explanations inside a step.
- If a step has no “next action,” merge it with the previous one or turn it into a short note.

---

## 8. Deletability check

- For every block, ask: **“If I remove this, what breaks?”** If the reader can get the same information elsewhere or from a linked doc, shorten or remove it.
- Prefer **pointing to authoritative docs** over restating their content (e.g. “see [official guide](url)” instead of repeating the steps).

---

## Quick checklist

| Check | Example |
|-------|--------|
| Entry points visible? | Main URLs or paths near the top of the relevant section |
| No duplicate explanations? | Each flow or concept explained once; other sections refer or summarize |
| Prerequisites as a list? | Unordered list of what’s needed (tools, accounts, etc.) |
| Steps numbered when sequential? | 1. Do X. 2. Do Y. 3. Share / run / etc. |
| Links in flow? | “[Service name](url)” in the sentence, not “[click here](url)” at the end |
| Wording matches usage? | Terms that match how the thing is actually used (context, not jargon) |

---

Keep this guide next to your docs (e.g. in a `docs/` folder or repo root) and use it when writing or reviewing README and other project documentation.