Skip to content

Maintain the documentation

Purpose

Create or update accurate pages without duplicating volatile facts, exposing secrets, breaking navigation, or confusing historical and current systems.

Prerequisites and impact

Read the evidence model, current inventory, affected service page, workflow, and relevant scripts. Documentation edits do not authorize live infrastructure changes. Preserve unrelated work.

Choose the content type

Need Type Location
Learn by doing Tutorial docs/tutorials/
Complete a task How-to/runbook docs/operations/
Look up exact facts Reference docs/current/, docs/reference/, service pages
Understand architecture Explanation docs/current/index.md and focused explanations
Preserve rationale ADR docs/decisions/
Preserve superseded state History docs/history/ or a clearly marked compatibility page

Add or update a service page

  1. Confirm the service in the service catalog.
  2. Record lifecycle, owner, criticality, recovery priority, verification date, version/image, host/runtime user, network, dependencies, listeners, paths, data, logs, and secret locations.
  3. Document clean reconstruction, configuration, start/stop/status/logs, upgrade, backup, restore, validation, rollback, security, monitoring, and symptom-based troubleshooting.
  4. Use commands observed in scripts or read-only live checks. Include expected results.
  5. Link volatile inventory facts rather than copying them.
  6. Link primary upstream documentation.

For a Podman/Quadlet service, also record:

  • /home/podsvc/.config/containers/systemd/<name>.container;
  • /opt/podman/config/<name>/;
  • /opt/podman/env/<name>.env without values;
  • /opt/podman/volumes/<name>/;
  • networks, container UID/GID ownership, high ports, Caddy route, and backup.

Add or update a VM or LXC

  1. Run qm config <VMID> or pct config <CTID> through ssh pvessh.
  2. Record ID, name, lifecycle, resources, disks, bridge/VLAN, startup, guest type, ownership, criticality, recovery priority, and evidence date.
  3. Add the canonical row to current inventory.
  4. Create a separate page only when the guest has enough operational detail to justify it; otherwise link to its service page.
  5. Update dependencies, network, backup, and service catalog when affected.

Add network, DNS, ingress, storage, or hardware facts

  1. Validate from the authoritative system.
  2. Update the single canonical table: network, inventory, or hardware.
  3. State confidence and date.
  4. Add a runbook or ADR when change procedure or rationale matters.
  5. Never infer a current value from a historical export.

Document a change without secrets

  1. State the purpose, approved window, impact, and rollback.
  2. Record names and paths, never values.
  3. Redact exports using configuration redaction.
  4. Capture commands and expected results without unrestricted env, inspect, database dumps, or private configuration.
  5. Record the result as an observation, not conversational narration.

Diagrams and screenshots

  1. Update the editable source when available.
  2. Verify every label against the canonical inventory.
  3. Remove credentials, tokens, cookies, account names, public IPs when unnecessary, and metadata.
  4. Use SVG for diagrams and WebP/PNG for screenshots.
  5. Add useful alt text; do not rely on color alone.
  6. Prefer first-party documentation images or locally captured, redacted screenshots. Record source URL, retrieval date, license, and modifications in the image source register.
  7. Caption generic or older UI examples so readers do not mistake their values for current KH3 configuration.
  8. Keep old diagrams only under clearly historical context.

Update navigation

  1. Add the source path once in mkdocs.yml.
  2. Use visible lifecycle labels such as “Historical”.
  3. Update inbound links before renaming a page.
  4. Prefer a compatibility page when an established URL changes.
  5. Run QA to detect missing, duplicate, or unintentionally omitted pages.

Build and review

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

Inspect site/index.html, current architecture, inventory, the changed runbook/service, history, and navigation. Never stage site/.

Rollback and troubleshooting

Use git restore <path> only for a file whose changes are known to be disposable. Do not use a broad reset in a dirty worktree.

Symptom Remedy
Broken relative link Correct it relative to the source page and rerun QA
Duplicate H1/nav entry Keep one canonical title/entry and link to it
Omitted page Add it to nav or the explicit historical exclusion policy
Conversational agent prose Convert it to fact, procedure, warning, incident, ADR, or unverified item
Strict build warning Treat it as failure; fix the source or navigation

Official references