Documentation playbook

A documentation playbook for any project on any stack. Docs are how a new developer, a customer, an operator at 3 in the morning and a coding agent learn what your software does. Wrong docs are worse than none, because people and agents follow them. Every rule here has a check that a build or a script can run.

The chapters follow the readers. First come the four kinds of docs and who each one serves, then the README and the docs that live in the repository. Next are reference docs, changelogs and migration guides, generated where they can be. After that come docs that coding agents read, and examples that run as tests. The last chapters cover help centres for end users and keeping every page dated, owned and current, or deleted.

Start with Sort every page into one of four kinds. Then read Use only made-up data in docs before you paste the next screenshot.

Some topics have their home elsewhere. The engineering playbook's Documentation chapter holds the base rules. They cover the quick start, docs in each pull request, decision records, runbooks, generated reference, changelogs, tested docs and owners. This playbook builds on those rules and links to them. The instructions file for agents lives in Setting up the project. API contracts live in the API design playbook's Contracts and docs.

Chapters

1. Kinds 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

2. README and docs as code

   Give the README a fixed set of sections. Keep every doc in the repository with one index, and build and check the docs in CI like code.

   • Recommended 4
   • Optional 1

3. Reference and changelogs

   Keep docs for every supported version, give each error and setting a generated page, and log deprecations, security fixes and migrations.

   • Recommended 5

4. Docs for coding agents

   Point the agent instructions file at the docs instead of copying them. Publish docs agents can fetch, and keep out hidden text and unmarked dangerous steps.

   • Recommended 4
   • Optional 1

5. Examples that run

   Write examples a reader can copy and run, and mark every placeholder. Use only made-up data, and make screenshots with a test so they match the product.

   • Required 1
   • Recommended 4

6. Help centres and user guides

   Write help articles around the tasks customers come with, make instructions accessible as the law asks, link help from the screen, and fix failed searches.

   • Required 1
   • Recommended 4
   • Optional 1

7. Keeping docs current

   Date every page and write nothing that goes stale with time. Fail the build on names that no longer exist, and delete unused pages with a redirect.

   • Recommended 5
   • Avoid 1

All 37 rules on one page

This is a lot to check. An Expert can check it for you.

Related playbooks

• Documentation

  In the Engineering playbook. The base rules for docs in the repository. One-command quick start, docs in the same pull request, runbooks, decision records and owners.

• Setting up the project

  In the AI-assisted development playbook. Coding agents read one instructions file on every task. Set it up so it points at your docs instead of copying them.

• Contracts and docs

  In the API design playbook. API reference comes from the contract. Write the OpenAPI file first and generate the docs and examples from it.

• HTML basics

  In the Website playbook. A docs site is a website. Titles, headings, language and metadata decide whether people and search engines find the right page.

• Messages and translation

  In the Localization playbook. Translated docs go stale when the source changes. Track every translation and fail the build on missing ones.