End-User Documentation Checklist

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.