Skip to content

Documentation Quality Guide

Purpose

Define the baseline quality checks for documentation updates so docs remain accurate, navigable, and executable.

Required Checks

  1. verify links resolve to existing pages
  2. verify nav is updated for added or moved pages
  3. verify command examples are valid for the described runtime mode
  4. verify related index pages and cross-links are updated

Validation Commands

# internal markdown links
python3 .github/scripts/check_internal_md_links.py

# strict mkdocs build

docker run --rm \
  -v "$PWD":/docs \
  -w /docs \
  squidfunk/mkdocs-material:latest \
  build --strict -f mkdocs.yml

Writing Rules

  • keep one canonical page per topic and cross-link from related pages
  • use warnings for risk-prone actions and tips for shortcuts
  • separate local, deploy, and operations contexts clearly
  • keep reference pages factual and task pages action-oriented

Drift Prevention Checks

  • compare URL docs against active route configuration
  • compare module docs against current ownership boundaries
  • compare service docs against compose and runtime config
  • compare env-var docs against actual configuration usage