eSlider
e6e57843cb
CI & Release / Verify documentation (push) Skipped
CI & Release / Verify simulator (push) Skipped
CI & Release / Trivy scan (push) Skipped
CI & Release / Semantic Release (push) Skipped
CI & Release / Verify documentation (pull_request) Successful in 5s
CI & Release / Verify simulator (pull_request) Failing after 9s
CI & Release / Trivy scan (pull_request) Skipped
CI & Release / Semantic Release (pull_request) Skipped
Enforce link resolution, glossary anchors, and readability rules on every push and PR; docs-only pushes to main still run docs-verify while skipping the simulator gate.
2.5 KiB
2.5 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.mdbare cross-reference to doc 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)
Implemented in scripts/check_docs.py — see ci-rules.md.
Files touched
docs/00–12, docs/adr/*, nine READMEs, root README.md.