Agent WranglersKinds of docs
Sort every page into tutorial, how-to guide, reference or explanation. Each kind serves one need, and mixing them on one page fails every reader at once.
- Recommended 4
- Avoid 1
Recommended
Sort every page into one of four kinds
DOC-1Give every docs page one kind from a fixed list of tutorial, how-to guide, reference and explanation. Group the docs index by kind.
Write how-to guides as numbered steps toward one goal
DOC-2Title each how-to guide with the goal, list what the reader needs first, give numbered steps, and end with a way to confirm it worked.
Test every tutorial from a clean start
DOC-3Run every tutorial from start to end in CI, in a fresh environment. Run it on every change to the tutorial or its code, and once a week.
Write docs in plain words for the named reader
DOC-5Write every page for the reader its front matter names. Keep sentences under 25 words, define each term on first use, and lint the prose in CI.
Avoid
Mixing kinds of docs on one page
DOC-4Never put long background in a how-to guide or tutorial, or steps in a reference page. Link to the page of the other kind instead.
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/documentation/kinds-of-docs">Agent Wranglers documentation playbook</a>. In code you write, add a comment next to it with the same link.