developer-docs-structure-audit

Run a full page inventory first, then classify each page against the Diátaxis modes (tutorial, how-to, reference, explanation), build a coverage matrix of product surfaces, and score sections on the CNCF TechDocs rubric. The bundled docs-inventory.py script automates the per-page data collection.

A Diátaxis audit classifies every documentation page by its dominant mode using two questions: does the content inform action or cognition, and does it serve study or work. Pages mixing modes or sitting in the wrong section become findings with concrete fixes.

The docs-inventory.py script works with MkDocs, Docusaurus, Sphinx, VitePress, Mintlify, Starlight, Nextra, GitBook, and others by extracting path-like tokens from any navigation config format. It handles Markdown, MDX, and reStructuredText files.

Yes, but with reduced scope: diff the sitemap against the rendered navigation for orphan candidates and drop staleness and orphan measures from the scorecard since drafts and last-modified dates are invisible. Label the inventory as nav-only in the report.

Cancel a restructure when tree testing shows roughly 80% task success and 60% direct-path rates, since structure is not the bottleneck. Also avoid empty four-section scaffolding and full teardowns; ship small single actions that each improve the docs independently.

The audit covers placement, coverage, and findability only; it does not verify content accuracy, edit prose, or check that code samples run. Those issues are noted separately with an owner rather than reported as structural findings.