docs: audit links, glossary T0-T4, readability pass

Extend glossary with storage floors, source of truth, and linkable anchors. Fix broken links, pose frame drift, rsync/offload wording, and README tone. Add docs/improvement audit records and live demo links in design journey.
2026-07-10 10:46:59 +01:00
parent ed531f9fb6
commit 5f6fd8462c
27 changed files with 376 additions and 193 deletions
@@ -0,0 +1,74 @@
+# Documentation audit — 2026-07-10
+
+Manual pass over `docs/`, all READMEs, and glossary. Goal: correct links, unify T0–T4 vocabulary, align rsync/offload wording with code, improve readability.
+
+## Summary
+
+| Metric | Result |
+| --- | --- |
+| Markdown files checked | 33 |
+| Broken relative links (after fixes) | 0 |
+| Glossary `###` anchors added | 15 (T0–T4, layers, bulk sync, source of truth, …) |
+| Open questions added | §12–§14 (tooling, DuckLake, `schemas/`) |
+
+## Findings fixed
+
+### Links
+
+- `infra/terraform/ground/README.md` pointed at non-existent `03-storage-design.md` → `03-data-platform.md`.
+- `11-cicd-delivery.md` bare `see 05` → proper markdown link.
+
+### Factual drift (code vs docs)
+
+| Item | Was | Now (matches `broadcast.py`, `sim.ts`) |
+| --- | --- | --- |
+| Pose frame | ~40 bytes, uint16 `drone_id` | 46 bytes, 8-byte ASCII `drone_id` |
+
+### Terminology
+
+- Extended [00 — Glossary](../00-glossary.md) with T0–T4, architecture layers, pipeline stages, source of truth.
+- Disambiguated design journey §4: pipeline stages ≠ storage floors.
+- Roadmap Stage 7: rsync bulk path, not “MinIO replication”.
+
+### rsync / rclone / offload
+
+| Path | Canonical tool |
+| --- | --- |
+| Peer bulk sync | rsync over SSH |
+| Dock offload | rsync or `mc mirror` |
+| S3 backends (optional) | rclone |
+| Sim CronJob | `cp -ru` + `mc mirror` (documented shortcut) |
+
+### Live demos (design journey)
+
+- [swarm.produktor.io](https://swarm.produktor.io/) — visual prototype
+- [swarm-data-explorer.produktor.io](https://swarm-data-explorer.produktor.io/) — SQL explorer
+- [swarm-analalytics.produktor.io](https://swarm-analalytics.produktor.io/d/swarm-fleet/swarm-fleet-e28094-generated-data?orgId=1&refresh=5s) — Grafana fleet dashboard
+
+### README / LICENSE
+
+- Restricted-use notice with link to [LICENSE](../../LICENSE).
+- Component READMEs tightened (caveman style).
+
+## Remaining (documented, not bugs)
+
+| Item | Where |
+| --- | --- |
+| `schemas/` directory absent | OQ §14, roadmap stage 2 |
+| DuckLake undecided | OQ §13 |
+| rsync bulk sync not in sim code | Design only |
+| Glossary table terms link to section headers, not row anchors | Optional polish |
+| T4 after “Source of truth” in glossary order | Cosmetic |
+| GitOps “source of truth” vs data SSOT | Different meanings in `11-cicd-delivery` |
+
+## Suggested CI checks (for issue #1)
+
+```bash
+# Relative .md link resolver (Python one-liner in audit script)
+# Glossary anchor: every 00-glossary.md#... from docs/ must resolve
+# Optional: markdown-spellcheck with US locale
+```
+
+## Files touched
+
+`docs/00`–`12`, `docs/adr/*`, nine READMEs, root `README.md`.
@@ -0,0 +1,18 @@
+# Documentation improvement records
+
+Point-in-time audits and follow-up work for links, terminology, readability, and factual alignment with code.
+
+| Report | Date | Scope |
+| --- | --- | --- |
+| [2026-07-10 audit](2026-07-10-audit.md) | 2026-07-10 | Full `docs/` + README pass; glossary T0–T4; live demo links |
+
+## Future automation
+
+Tracked in [issue #1](https://git.produktor.io/eSlider/swarm-house/issues/1): CI link checker, glossary anchor validation, terminology lint.
+
+## How to add a new report
+
+1. Copy the structure from the latest audit file.
+2. Name it `YYYY-MM-DD-short-topic.md`.
+3. Add a row to the table above.
+4. Cross-link from [09 — Open questions](../09-open-questions.md) if new ambiguities appear.