Documentation Structure

Documentation Structure Audit

Scope

Document structure only: heading hierarchy, section ordering, presence of required sections (introduction, prerequisites, steps, reference), file naming, metadata blocks, navigation, and cross-references.

Inputs

• Documentation file(s) under review.
• Documentation directory structure.
• Diataxis classification output (from the documentation-diataxis skill, when run as part of the orchestrated review).

Actions

1. File Naming:

   Verify files use lowercase with dashes and the correct extension for their syntax (for example, connect-vscode.rst for reST, connect-vscode.md for MyST).

2. Metadata:

   Ensure every page has required metadata near the top when the repository's docs conventions require it: .. meta:: after the anchor label for reST, or the MyST equivalent (front matter or meta directive) for Markdown sources.

3. Directory Placement:

   Confirm the file is located in the directory matching its intended Diataxis category (for example, tutorials in tutorial/, how-to guides in how-to/).

4. Navigation:

   Ensure new pages are added to the toctree.

5. Cross-References:

   • Prefer stable reference roles (:ref: for reST, {ref}/{numref} for MyST) over page-level links.
   • Flag uses of :doc:/{doc} (or equivalents) except for index-like pages that are unlikely to be moved or renamed.
   • Suggest adding links to improve documentation discoverability.
   • Verify cross-references resolve correctly.

6. Verification:

   Confirm the structural audit completed:

   • File naming checked for all files
   • Metadata presence verified
   • Directory placement validated (using Diataxis classification if available)
   • Navigation structure checked (toctree entries)
   • Cross-references validated

   State the completion status:

   • ✓ Structure audit complete: [N] violations found
   • OR ✓ Structure audit complete: No violations found

Constraints

• Do not modify files during the audit; this is a read-only review.
• Do not invent metadata requirements; check against repository's documented conventions.
• Focus on structural issues only; do not flag style preferences.
• When Diataxis classification is available (from orchestrated review), use it to validate directory placement. Otherwise, infer from directory name.

Output

A list of structural or metadata violations covering file naming, metadata, directory placement, navigation, and cross-reference issues.

Source: canonical/charmcraft — distributed by TomeVault.