07 — Documentation and Developer Experience Checklist#

Verify that developers and operators can find accurate information, reproduce their local environment, understand API and system behavior, make changes safely, and maintain the product without relying on undocumented knowledge.

Scope: Shared / cross-cutting. This file is one part of the 07_Documentation_and_DeveloperExperience.md checklist. Apply the domain-wide release gate across all applicable scope files; each checklist ID remains unique.

Review details#

• Project / product:
• Release / version / environment:
• Scope and applicable jurisdictions / markets:
• Documentation audiences / supported platforms:
• Documentation and developer-tooling owners:
• Reviewer / owner:
• Review date:
• Decision: Pending / Approved / Approved with documented exceptions / Blocked

How to use#

1. Copy this shared checklist into project-specific review records; leave every checkbox in the repository unchecked.
2. Mark [x] only after verifying the item from current guides, a reproducible setup, a working code example, documentation checks, or a documented ownership decision. Track failed items and genuine N/A rationales in project-specific notes or issues using the DOC ID; do not add evidence tables to shared templates.
3. Favor reader outcomes over document count: assess whether a representative developer can find instructions, complete a task, and diagnose common failures. Adapt to the system's language, audience, deployment model, and risk.
4. Evaluate ## API Checks and ## Frontend Checks separately where applicable, recording N/A and why outside this template for products without those interfaces.
5. Recheck critical docs and developer workflows when releases, dependencies, API contracts, deployment processes, ownership, or supported platforms change. Coordinate formal compliance, security, accessibility, and test-coverage requirements with the corresponding checklists.

Project documentation#

• DOC-001 Identify the documentation audiences, including new developers, maintainers, operators, integrators, and product users, and their top tasks.
• DOC-002 Ensure the primary project entry point explains the product's purpose, supported scope, prerequisites, and where to get help.
• DOC-003 Provide a clear path from the project entry point to installation, first successful use, contribution guidance, and deeper references.
• DOC-004 Organize documentation so readers can find tutorials, task-oriented how-to guides, technical reference, and conceptual explanations where appropriate.
• DOC-005 Name pages and headings using terms readers search for rather than internal team labels or ambiguous acronyms.
• DOC-006 Assign an accountable owner and a review cadence to each critical documentation area.
• DOC-007 Distinguish supported behavior, experimental features, deprecated features, and planned functionality explicitly.
• DOC-010 Include expected results and success criteria for high-impact setup, configuration, or operational procedures.
• DOC-011 Use accurate, runnable code and command examples with prerequisites and safe placeholder values.
• DOC-012 Keep examples free of live credentials, sensitive customer data, unsafe defaults, and unapproved external endpoints.
• DOC-013 Link related procedures and concepts near the point where readers need more context; avoid dead-end pages.
• DOC-015 Use consistent terminology, units, file paths, configuration names, and formatting across related pages.
• DOC-016 Write concise steps with explicit actions and observable outcomes; explain non-obvious risks before destructive operations.
• DOC-017 Provide text alternatives, semantic headings, meaningful links, and accessible tables/images where documentation formats support them.
• DOC-018 Keep changelogs or release notes accurate about changes that affect users, developers, or operators.
• DOC-019 Document important functional limitations, environmental constraints, and compatibility considerations without marketing-only claims.
• DOC-020 Review key guides with representative readers to confirm they can complete the intended tasks unaided.

Developer setup and tooling#

• DOC-022 Provide a repeatable step-by-step setup from a clean workstation or development environment to a running local application.
• DOC-023 Define where to obtain required repository access, test accounts, licenses, and development-only credentials without sharing secrets.
• DOC-024 Maintain a safe example configuration file or documented variable inventory with descriptions and non-secret defaults.
• DOC-025 Document dependency installation, lockfile usage, and any build artifacts or external services required to start development.
• DOC-026 Offer a single obvious development start command or a clearly ordered equivalent set of commands.
• DOC-028 Provide synthetic or approved nonproduction sample data and document how to seed and reset it.
• DOC-029 Explain how to run unit, integration, contract, and end-to-end checks relevant to the project.
• DOC-030 Document local formatting, linting, type-checking, and other quality commands, including how they match CI checks.
• DOC-032 Explain how to test changes against external integrations safely, including mocks, sandboxes, and permitted test endpoints.
• DOC-033 Document common environment-specific failures and proven troubleshooting steps with distinguishable symptoms.
• DOC-034 Make errors from setup scripts actionable rather than returning an unexplained nonzero exit status.
• DOC-035 Use pinned or declared tool versions, containers, or bootstrap tooling where it meaningfully reduces setup drift.
• DOC-036 Test onboarding instructions periodically using a clean environment or an engineer unfamiliar with the project.
• DOC-037 Clarify which tasks require elevated privileges and avoid recommending unnecessary broad permissions.
• DOC-038 Describe required environment variables, build flags, feature flags, and the observable effects of toggling them.
• DOC-039 Keep common development workflows discoverable through task runners, documented scripts, or a lightweight developer portal where useful.
• DOC-040 Document how to validate changes locally before committing and how developers can interpret failing CI results.
• DOC-041 Track time-to-first-success, recurrent setup blockers, or developer feedback to prioritize high-friction workflow improvements.
• DOC-042 Define supported cleanup/reset commands so failed local experiments do not leave stale processes or contaminated test data.

API and architecture documentation#

• DOC-043 Provide a current system context diagram or equivalent description of components, external dependencies, and trust/data boundaries.
• DOC-044 Explain the responsibility and ownership of major modules, services, data stores, and integration points.
• DOC-045 Document important architectural decisions, alternatives, constraints, and consequences in discoverable records.
• DOC-046 Keep architecture descriptions synchronized with real implementation and clearly identify superseded diagrams or proposals.
• DOC-047 Document critical data entities, source-of-truth boundaries, and meaningful consistency or transaction assumptions.
• DOC-048 Describe operationally significant message flows, background jobs, event consumers, and failure-handling responsibilities.
• DOC-050 Explain the intended stability, lifecycle, and compatibility policy for public or cross-team interfaces.
• DOC-053 Describe authentication methods, scopes, authorization expectations, and how consumers obtain safe test credentials.
• DOC-054 Document pagination, sorting, filtering, idempotency, and concurrency semantics where they affect client implementations.
• DOC-056 Document rate limits, quotas, timeout behavior, retries, and recovery steps for unavailable dependencies.
• DOC-060 Ensure interface examples are tested or generated from authoritative contracts so they do not drift from production.

Maintenance and onboarding#

• DOC-064 Explain repository contribution conventions, required checks, expected review behavior, and issue/commit practices as applicable.
• DOC-066 Provide a guided first contribution or safe starter task with prerequisites and completion criteria for new team members where useful.
• DOC-067 Maintain current service ownership and escalation information for critical components and support contacts.
• DOC-068 Keep operational runbooks for common failures, incident triage, restoration, and emergency actions where risk warrants them.
• DOC-069 Verify runbooks contain prerequisites, authorized access paths, commands, expected outcomes, and stopping/rollback points.
• DOC-070 Provide clear instructions for transferring ownership, rotating credentials, renewing certificates, and other time-sensitive maintenance tasks.
• DOC-072 Keep a changelog or change-summary process for documentation, interface changes, and operational procedures.
• DOC-073 Store documentation with a reviewable history and integrate its updates into relevant feature or release changes.
• DOC-074 Use automated checks for broken links, formatting, stale code snippets, and site builds where tooling supports them.
• DOC-075 Validate crucial examples or command sequences in CI or periodic manual checks, with documented coverage gaps.
• DOC-076 Define versioning, archiving, and redirect policies to prevent obsolete guides from misleading current users.
• DOC-077 Remove or clearly mark unsupported, duplicated, or superseded procedures and link to their replacements.
• DOC-078 Set documentation review triggers for incidents, failed onboarding, recurring support issues, and product behavior changes.
• DOC-079 Review and triage documentation feedback using owners, priority, and response targets.
• DOC-080 Ensure critical internal knowledge does not exist only in personal chats, private laptops, or one unmaintained person's notes.
• DOC-082 Measure discoverability, correctness, setup success, or support burden through appropriate feedback and task-based validation.

Release gate#

• Critical readers can discover the current getting-started, support, architectural, and operational documentation appropriate to their responsibilities.
• Setup and essential development, test, or build commands have been exercised successfully on a supported clean environment or have an approved, documented risk-based alternative.
• Public or cross-team API/interface references and associated runnable examples match the release candidate, with visible compatibility and migration guidance where relevant.
• Frontend component, accessibility, data-state, and deployment guidance is updated for affected UI features where applicable.
• Critical operational runbooks, ownership contacts, and incident escalation paths are accurate and available to authorized responders.
• Documentation errors affecting essential onboarding, safe operations, or integration are fixed, or have explicit authorized dispositions and tracked remediation.
• A named owner has reviewed documentation currency, broken links, and unresolved feedback for the exact release being approved.

Domain-specific approval rule: Block documentation/enablement sign-off when a critical setup cannot be reproduced, the documented interface contradicts deployed behavior, a destructive procedure is misleading, or essential operational steps or owners are missing without authorized mitigation. Passing this checklist does not substitute for testing, security, accessibility conformance, or legal review.

Trusted references and scope#

These sources inform practical, verifiable documentation and developer-experience review tasks. They are not universal certification standards or verbatim rules for every software project.

• Diátaxis — Documentation framework — organizing tutorials, how-to guides, reference, and explanation by reader need.
• DORA — Documentation quality — documentation clarity, findability, reliability, and developer effectiveness.
• Write the Docs — Docs as code — version control, review, automated tests, and shared documentation ownership.
• Google developer documentation style guide — clear, consistent, audience-centered technical writing.
• Google developer documentation — Code samples — formatting, introducing, and explaining runnable code samples.
• Microsoft Writing Style Guide — Code examples — task-focused, safe, tested code examples with expected results.
• Microsoft Writing Style Guide — Writing for all abilities — clear, accessible language and alternative interaction guidance.
• GitHub Docs — About README files — project purpose, getting started, support, and repository discoverability.
• GitHub Docs — Guidelines for repository contributors — documenting contribution workflows and expectations.
• GitHub Docs — About CODEOWNERS — repository ownership and review routing when used.
• OpenAPI Specification v3.2.1 — machine-readable descriptions of HTTP API operations and contracts.
• W3C WAI — Headings — accessible document heading structure and navigation.

Applicability: Documentation types and review depth depend on project size, audience, release risk, language, and support model. GitHub-specific contributor features, CODEOWNERS, shared design systems, formal OpenAPI descriptions, and public API quickstarts are conditional; choose equivalent controls where appropriate. README.md in this checklist repository remains intentionally minimal and must not be changed without a separate request.

Source review date: 2026-11-12.

Suggested testing tools#

Choose tools appropriate to the project's stack and risks; automation supports evidence but does not approve the checklist.

• Test focus: links, snippets, onboarding setup, and API documentation examples; include shared/cross-team controls where applicable.
• Cross-stack: lychee + markdownlint-cli2.
• Python: doctest + pytest; for pytest-based suites, run python -m pytest -q.
• TypeScript: TypeDoc + Vitest; for Vitest-based suites, run npx vitest run (or npx playwright test for E2E).
• JavaScript: JSDoc + Jest; for Jest-based suites, run npx jest --ci (or npx playwright test for E2E).
• Evidence: Save tool versions, configuration, test environment, fixtures, results, and links in project-specific review records using the existing checklist IDs. Expert review remains necessary where relevant.

Suggested AI skills for verification#

These are optional agent review aids, not automated passes or release approval. Each linked repository had at least 1,000 GitHub stars when checked on 2026-11-12; counts are per repository, not per skill, and do not indicate security or correctness.

• documentation-and-adrs — Review documentation and decision-record accuracy (addyosmani/agent-skills, 116,378 repo stars).
• docs-sync-audit — Find documentation drift against code (github/awesome-copilot, 41,073 repo stars).
• doc-coauthoring — Review onboarding and instruction clarity (anthropics/skills, 193,495 repo stars).

How to check: In a project-specific copy, have the agent audit the shared / cross-cutting scope and map findings to this file's existing checklist IDs, with code/configuration references, reproducible test results, failed or inapplicable cases, and uncertainties. Independently verify findings; keep shared template boxes unchecked and retain human approval requirements.

Before use: Read the skill's SKILL.md, referenced scripts, license, and requested tool permissions. Only execute vetted skills with appropriate access in a controlled environment.

Important warning: reference only#

⚠️ Reference only — not a definitive or exhaustive checklist. This template is a starting point for review, not the ultimate authority or a guarantee of project safety, quality, regulatory compliance, accessibility, security, or launch readiness.

Use project-specific judgment and independent verification. Requirements and risks evolve and differ by project, technology, and jurisdiction. Adapt the checks, consult current authoritative sources, perform relevant tests, and obtain qualified specialist review or approval when appropriate. Checking every box does not replace these steps.