eSlider
5f6fd8462c
CI & Release / Verify simulator (push) Skipped
CI & Release / Trivy scan (push) Skipped
CI & Release / Semantic Release (push) Skipped
CI & Release / Verify simulator (pull_request) Failing after 4s
CI & Release / Trivy scan (pull_request) Skipped
CI & Release / Semantic Release (pull_request) Skipped
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.
2.6 KiB
2.6 KiB
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.mdpointed at non-existent03-storage-design.md→03-data-platform.md.11-cicd-delivery.mdbaresee 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 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 — visual prototype
- swarm-data-explorer.produktor.io — SQL explorer
- swarm-analalytics.produktor.io — Grafana fleet dashboard
README / LICENSE
- Restricted-use notice with link to 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)
# 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.