Documentation checklist

Every rule in the documentation playbook, by chapter, required rules first. Each links to its own page with how we built it and how to check it. This is a lot to check. An Expert can check it for you.

Kinds of docs

• Recommended DOC-1 Sort every page into one of four kinds
• Recommended DOC-2 Write how-to guides as numbered steps toward one goal
• Recommended DOC-3 Test every tutorial from a clean start
• Recommended DOC-5 Write docs in plain words for the named reader
• Avoid DOC-4 Mixing kinds of docs on one page

README and docs as code

• Recommended DOC-6 Give the README a fixed set of sections
• Recommended DOC-7 Keep one docs index that links every page
• Recommended DOC-8 Build the docs in CI and fail on every warning
• Recommended DOC-10 Link each decision record from the code it governs
• Optional DOC-9 Publish a preview of the docs for every pull request

Reference and changelogs

• Recommended DOC-11 Keep a docs version for every supported release
• Recommended DOC-12 Give every error code its own docs page
• Recommended DOC-13 Generate the settings reference from one schema
• Recommended DOC-14 Log deprecations and security fixes in their own sections
• Recommended DOC-15 Write a migration guide for every major version

Docs for coding agents

• Recommended DOC-16 Point the instructions file at the docs instead of copying them
• Recommended DOC-17 Publish the docs in a form agents can fetch
• Recommended DOC-18 Put a stop before every destructive step in a runbook
• Recommended DOC-19 Fail the build on hidden characters in docs
• Optional DOC-20 Test the docs with a fresh agent

Examples that run

• Required DOC-23 Use only made-up data in docs
• Recommended DOC-21 Make every example complete enough to copy and run
• Recommended DOC-22 Write placeholders in capitals and explain each one
• Recommended DOC-24 Make screenshots with a test from a demo account
• Recommended DOC-25 Show each API example in every language you ship an SDK for

Help centres and user guides

• Required DOC-27 Make product instructions accessible as the law requires
• Recommended DOC-26 Name help articles after the task people came to do
• Recommended DOC-28 Make docs pages pass the same accessibility checks as the product
• Recommended DOC-29 Link help from the screen where people get stuck
• Recommended DOC-30 Fix the help searches that find nothing
• Optional DOC-31 Ask on every article whether it helped

Keeping docs current

• Recommended DOC-32 Show the last-updated date on every docs page
• Recommended DOC-34 Fail the build when docs name something that no longer exists
• Recommended DOC-35 Label deprecated features on their docs pages
• Recommended DOC-36 Delete docs nobody needs and redirect their address
• Recommended DOC-37 Show readers when a translation is older than the source
• Avoid DOC-33 Writing time words that go stale

Show the badge on your project

When your project passes every Required rule, you can show this badge on your site or in your README. It links to this checklist, so anyone can run the same checks.

<a href="https://agentwranglers.se/playbook/documentation/checklist"><img src="https://agentwranglers.se/badge.svg" alt="Checked against the Agent Wranglers documentation playbook" width="214" height="20"></a>

[![Checked against the Agent Wranglers documentation playbook](https://agentwranglers.se/badge.svg)](https://agentwranglers.se/playbook/documentation/checklist)