Skip to content

Documentation validation

Repeatable procedure to verify repo documentation matches live homelab reality. Record results in a dated journal entry (docs/journal/YYYY-MM-DD-documentation-validation.md).

When to run

  • After a phase milestone (Phase 7 DNS, Tailscale, etc.)
  • Before handing the repo to another operator
  • Quarterly, or when README.md Owner TODO and reality diverge

1. Live smoke tests

Run from a machine on the LAN with SSH to managed hosts.

DNS (AdGuard)

ssh someone@192.168.6.17
dig @192.168.6.17 google.com +short
dig @192.168.6.17 infra-services.lab.local +short
docker ps --format '{{.Names}}' | grep -i adguard

Pass: public A record; rewrite returns 192.168.6.17; container listed.

Tailscale

ssh someone@192.168.6.17 'tailscale status | head -20'

Pass: infra-services, proxbox-cube, saltierpoop online with expected tags.

ACL GitOps

gh run list --repo notarealemail/homelab --workflow=tailscale-acl.yml --limit 1

Pass: latest run success after any infra/tailscale/** change.

Off-LAN (optional)

From phone on cellular + Tailscale subnets enabled:

  • https://100.71.93.130:5001 — DSM
  • https://192.168.6.17 — subnet route to Servers VLAN

2. Repo checks

cd homelab
uv sync
uv run mkdocs build --strict
uv run python scripts/lint-markdown.py

Pass: mkdocs strict build exits 0; no broken internal links.

Stale language grep

rg -i 'to do|in progress|not deployed|REPLACE_ME' docs/ --glob '*.md' | rg -v 'documentation-validation|phase-7r-audit|lab-audit|network-observations'

Review hits manually — historical runbooks may legitimately contain past tense.

Owner TODO

Open README.md Owner TODO table. Every :white_check_mark: must be true; every :black_square_button: must still be open work.

Phase runbooks

3. mkdocs nav audit

Compare mkdocs.yml nav: to files under docs/:

# List all markdown under docs except hidden
find docs -name '*.md' | sort

Every nav entry must resolve. Files not in nav should be linked from an index page or marked as historical in the validation journal.

4. Write evidence

Create or update:

  1. docs/journal/YYYY-MM-DD-documentation-validation.md — pass/fail table, command output summaries, list of doc files changed
  2. docs/journal/YYYY-MM-DD-checkin.md — narrative summary (optional if minor)
  3. Row in journal/index.md

5. Publish

Merge to main. Confirm Deploy Docs workflow succeeds and hldocs-c0acdec9.pages.dev shows the new journal entry.