git:20261017.6c6369a to git:20261017.c52b424

---

name: docs

description: "Use when writing or updating docs, READMEs, changelogs, ADRs or PR text, or when a change alters setup, commands, APIs or documented behavior."

license: MIT

metadata:

sources: "MCT (local) ~/.claude/skills/docs-maintainer; cursor/plugins pstack 0.15.25 skills/technical-writing, skills/unslop"

---

# Docs

Docs are part of the change. When behavior, setup, commands, config or an API changes, the docs that describe it change in the same diff. When nothing a reader relies on changed, leave the docs alone.

## 1. Find what drifted

Grep for every changed name: command, flag, env var, config key, route, function, error message.

```bash

grep -rn "<name>" --include="*.md" --include="*.mdx" --include="*.txt" .

```

Also check `--help` and usage strings, docstrings and comments, `.env.example`, OpenAPI or GraphQL schemas, example and template files, and in-app help text.

- Replace stale instructions. Old and new steps side by side leave readers guessing which one works.

- Write what users need to act. Leave implementation detail out unless it changes what they do.

Done when: every hit is updated or confirmed still true.

## 2. Pick one mode per doc

Diátaxis splits docs by what the reader is doing:

| Mode | Reader | Write |

|---|---|---|

| Tutorial | Learning by doing | "We" build one thing step by step; every step shows its expected result |

| How-to | Has a goal | Steps to that goal, titled by the task ("How to rotate the API key"); no background |

| Reference | Looking something up | Dry, complete facts, structured like the thing described; generate from code where possible |

| Explanation | Wants to know why | Context, trade-offs, history, alternatives; the only mode with opinions |

Don't mix modes in one document. Split them and link between them.

## 3. Follow the file's convention

Match the repo's existing format first. Where none exists:

**README.** One sentence on what it is and who it's for, then install, a quickstart that runs as written, configuration, and links to deeper docs. Put the common case first. Commands are copy-pasteable with real paths, and show expected output where it helps.

**CHANGELOG** ([Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)):

- `## [Unreleased]` at the top, then releases newest first as `## [1.4.0] - 2026-10-17` (ISO date, SemVer).

- Group entries under Added, Changed, Deprecated, Removed, Fixed, Security.

- Write each entry for users ("Fixed a crash when the config file is empty"), not as a commit log.

- Version compare links go at the bottom.

- Files generated by changesets or release-please are edited through their tool, not by hand.

**ADR.** Use the repo's folder (`docs/adr/`, `docs/decisions/`), else `docs/adr/NNNN-short-title.md`. Sections: Status, Context, Decision, Consequences. Write one when a decision is costly to reverse, surprising to a newcomer, or the result of a real trade-off. Once accepted, an ADR isn't rewritten: a new ADR supersedes it, and the old one's status becomes "Superseded by ADR-NNNN".

**PR text and commit messages.** The `ship` skill owns their structure and the commands that create them. This skill owns the prose: a briefing a reviewer reads in under a minute, saying what changed and why. Link logs and metric tables instead of pasting them.

**Code comments.** Say why, not what. Delete a comment that restates the line below it.

Done when: each file you touched follows its convention.

## 4. Write it plain

- Cut every word that does no work. "In order to" is "to".

- Use the short, everyday word, and the real symbol, file, flag or command name instead of a description of it.

- Address the reader as "you", in the present tense and active voice. Write steps as commands: "Run `make test`."

- Put the condition before the instruction: "To reset the cache, run …".

- One instruction per sentence. Split sentences past about 25 words.

- Headings carry the point in sentence case ("Pick one mode per doc", not "Modes").

- Numbered lists for sequences, bullets for everything else. Code in code font.

- Drop "simply", "easy" and "just" from instructions. If it were simple, the reader wouldn't be reading.

- Mix sentence lengths and be specific: "a column rename fails the build", not "schema changes can cause issues".

Then run the pass in `references/unslop.md` over all prose you wrote or edited.

Done when: the unslop pass finds nothing left to cut.

## 5. Check it

- Run each command you documented where it's safe to. A documented command that fails is a bug.

- Relative links resolve (check the target path exists) and anchors match real headings. Use the repo's link checker (`lychee`, `markdown-link-check`) if it has one.

- Counts, version numbers and file trees are true at this commit.

- Build the docs site only when docs render through the app or a docs build.

Done when: every documented command ran or is listed as untested with the reason, and every link resolves.