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.
75 lines
2.6 KiB
Markdown
75 lines
2.6 KiB
Markdown
# 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`.
|