End-User Documentation Checklist
Steps a technical writer or DX lead runs to ship end-user documentation alongside a software release — from audience definition through SME review through publishing on the docs site.
Audience and Scope Definition
-
Identify the primary user personas
Pull the persona definitions from product (admin, end user, integrator, etc.) and confirm which one this guide is for. A single article that tries to address admins and end users at once almost always fails both.
-
Set the technical level for this guide
Novice readers need a glossary and a getting-started walkthrough; advanced readers want curl examples and skip the click-through. Pick one and stay in that register through the whole article.
Collects list -
Capture the user's runtime environment
Note supported browsers, OS versions, mobile vs. desktop, and SSO provider if relevant. The setup section will reference these; getting it wrong here cascades into broken instructions on Safari or older Edge.
Content Drafting
-
Draft task-oriented procedures in active voice
Lead each procedure with the user's goal, not the UI element. "To invite a teammate" beats "The Members page." Keep steps numbered and one-action-per-step — split compound steps that combine a click with a verification.
-
Apply the style guide for product terminology
Run Vale or the team style linter against the draft. Common drift: "workspace" vs "organization" vs "team," "login" (noun) vs "log in" (verb), product name capitalization. Inconsistency here is what makes docs feel amateur.
-
Capture annotated screenshots and screencasts
Use CleanShot, Snagit, or Loom against a clean demo tenant — never real customer data. Match the release-candidate UI, not last quarter's. Annotate with arrows and numbered callouts that match the procedure steps.
Collects file -
Add a glossary for first-time users
Novice readers hit jargon — workspace, integration, webhook, API key — and bounce. Define each term inline on first use and link to a glossary page. Skip this only when the audience is already advanced.
Structure and Navigation
-
Split content into task, concept, and reference pages
Follow the Diátaxis framework: tutorials (learning), how-to guides (task), reference (information), explanation (understanding). One page that mixes all four is a page nobody can find via search.
-
Wire up the sidebar and table of contents
Update sidebars.js in Docusaurus or mkdocs.yml nav. Confirm the new article appears in the right category and that the auto-generated TOC catches every H2/H3.
-
Configure search indexing for the new pages
If using Algolia DocSearch, confirm the new URLs are in the crawler config and trigger a re-crawl. Self-hosted MkDocs picks up new pages on rebuild — verify by searching for a unique phrase from the draft.
Accessibility and Localization
-
Run a WCAG 2.1 AA accessibility audit
Run axe DevTools or Pa11y against the rendered page. Required for EU Accessibility Act (effective June 2025) and Section 508 federal contracts. Common failures: low-contrast inline code blocks, missing alt text, headings that skip levels (H2 → H4).
Collects list -
Add alt text and captions for all media
Decorative screenshots get empty alt (alt=""); informative ones describe the action being shown, not just "screenshot." Screencasts need transcripts or captions — Loom auto-generates these but they need a manual review pass.
-
Flag user-facing strings for translation
If the product ships in multiple locales, push the new content to Crowdin or Lokalise with the appropriate context strings. Include screenshots so translators understand UI references — "Save" can translate three different ways depending on whether it's a button or a verb.
Technical Review
-
Verify every CLI command and code sample
Copy each snippet into a fresh terminal or sandbox and run it end-to-end. Stale flags, removed endpoints, and renamed env vars are the most reported docs bugs. If snippets are runnable in CI (doctest, mdsh), let the pipeline catch this on every PR.
-
Confirm version compatibility and system requirements
State the minimum supported version of the product, SDK, Node/Python/Go runtime, and any peer dependencies. Pin the doc to a release tag (e.g., v2024.45) so users on older versions see the matching content via the version switcher.
-
Route the draft to engineering SME for review
Open a PR against the docs repo and request review from CODEOWNERS for the affected feature area. SMEs catch behavior nuances writers miss — error messages, race conditions, edge cases on free vs. paid tier.
Collects list -
Address SME feedback and re-request review
Resolve every PR comment explicitly — either apply the change or reply with reasoning. Push fixes as new commits (don't force-push) so the SME can review the delta. Re-request review when the thread is clean.
Publishing and Maintenance
-
Publish to the docs site behind the release tag
Merge the docs PR; CI deploys to Vercel or Netlify. Confirm the new page renders with no 404s on internal links and that the version dropdown shows the article under the correct release. Run a broken-link check (lychee or htmltest) post-deploy.
Collects url -
Announce in release notes and #product-updates
Add the doc link to the public changelog and post in the customer-facing Slack/Discord. Loop in customer support so first-line agents know the article exists when tickets reference the new feature.
-
Schedule the 90-day documentation review
Pull analytics (Google Analytics, Plausible, or the docs platform's built-in) on page views, search-without-results, and helpful/not-helpful votes. Revise sections with low scroll depth or high bounce. Rotting docs are worse than no docs because users stop trusting the site.
Use this template
Copy it to your account, customize the steps, and run it with your team in minutes.
Browse hundreds of free templates across every team and industry.
Back to template libraryRun End-User Documentation Checklist with your team
Customize the steps, assign roles, set a schedule, and keep a complete record for every run.