Skip to content

Documentation Maintenance

Overview

This repository is the operational source of truth. Documentation changes are part of infrastructure changes, not a separate cleanup activity.

Page Standard

Use these sections where applicable:

  1. Overview
  2. Purpose
  3. Architecture
  4. Installation
  5. Configuration
  6. Operational Procedures
  7. Troubleshooting
  8. Related Systems
  9. References

Hardware pages use Device Overview, Technical Specifications, Architecture, Configuration, Operational Procedures, Troubleshooting, Related Systems, and References.

  • Link the first occurrence of every named system to its dedicated page.
  • Use the names in the Infrastructure Index and Service Catalog.
  • Use relative links without .html.
  • Add a Related Systems section for backlinks and adjacent dependencies.

Images

  • Store local assets under docs/assets/.
  • Prefer WebP for photographs and SVG for diagrams/logos.
  • Add useful alt text and a caption.
  • Remove location data or secrets from screenshots.
  • Avoid remote images that can disappear or track viewers.

Operational Procedures

Before commit:

python3 scripts/docs_qa.py
mkdocs build --strict
git diff --check

For an infrastructure change:

  1. Update the dedicated system page.
  2. Update the dependency map if relationships changed.
  3. Update inventory, network, backup, and runbook pages when affected.
  4. Use exact commands and paths from the deployed environment.
  5. Mark unknown facts To be verified.
  6. Never commit credentials or unredacted exports.

Troubleshooting

  • Broken link: correct the relative target or create the missing placeholder page.
  • Missing image: restore the asset or remove the reference.
  • Duplicate facts disagree: keep the dedicated page authoritative and link to it.
  • Build differs from production: check the publishing runbook.