Organize by the reader’s need
Separate learning a task, completing a specific task, looking up facts, and understanding a concept. Diátaxis names these tutorial, how-to, reference, and explanation. Use that distinction where helpful rather than forcing every page into the same template.Build a maintainable knowledge path
- Identify critical tasks. Start with setup, first successful use, common errors, limitations, and safe recovery. Include evaluator questions that repeatedly delay buying decisions.
- Declare the authoritative location. Avoid competing answers across support posts, product pages, and downloadable PDFs. Link to the maintained source and make version applicability visible.
- Write executable instructions. State prerequisites, permissions, inputs, steps, expected results, and recovery options. Use test data and identify destructive or irreversible steps explicitly where they exist.
- Make navigation task-oriented. Provide useful titles, cross-links, search terms, and routes from relevant product screens. Keep reference details accessible without burying beginner guidance.
- Assign update ownership. Tie documentation review to product changes and recurring support issues. Record version or review date honestly; a visual edit does not mean the technical procedure was revalidated.
- Test with a fresh reader. Have someone follow the instructions in the supported environment without verbal help. Capture the first point of confusion and correct it in the page.
Worked example
A fictional integration guide says “connect your account” but omits the required administrator role. New users repeatedly encounter a permission error. The revised page states the role requirement before setup, shows the expected success state, and links to the access-request route. The reference page retains detailed field definitions; the tutorial uses a small test dataset. Separating these needs makes both pages easier to use without deleting useful technical information.Documentation review card
Measure usefulness
Review task success, failed searches, repeated support questions, and feedback quality. A highly visited troubleshooting page may reveal a product defect rather than documentation success. Use those signals to improve both the instructions and the underlying experience.Try it with your own work
Follow one important guide in the supported environment using test data. Write down the first missing prerequisite, unclear step, or unexplained result and fix it in the page.Sources and scope
- Diátaxis is the primary source for the four documentation needs; implementation and review steps here are original.
What to read next
Website strategy · Customer education · Self-service buying Chapter guide · All playbooksCopyright © 2026 Ivan Xu. All rights reserved. See the copyright and reuse terms. Canonical source: github.com/weilun88313/B2B-Playbook