eSlider
302de4024d
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 4s
CI & Release / Verify simulator (pull_request) Successful in 11s
CI & Release / Trivy scan (pull_request) Successful in 9s
CI & Release / Semantic Release (pull_request) Skipped
Drop duplicate external URLs from design journey; small PR #3 owns them.
69 lines
2.4 KiB
Markdown
69 lines
2.4 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 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](../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)
|
||
|
||
Tracked in [PR #3](https://git.produktor.io/eSlider/swarm-house/pulls/3) — explorer + Grafana links in `12-design-journey.md` §7/§9. Prototype link already on `main` §2.
|
||
|
||
### 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)
|
||
|
||
Implemented in [`bin/check_docs.py`](../../bin/check_docs.py) — see [ci-rules.md](ci-rules.md).
|
||
|
||
## Files touched
|
||
|
||
`docs/00`–`12`, `docs/adr/*`, nine READMEs, root `README.md`.
|