eSlider/swarm-house
1
0
Fork 0
Code Issues 2 Pull Requests 3 Actions Packages Projects 1 Releases 13 Wiki Activity

Auto-analyse links, text, improvements, readability #1

New Issue
Open
opened 2026-07-10 10:46:07 +01:00 by eSlider · 1 comment
eSlider commented 2026-07-10 10:46:07 +01:00
Owner
Copy Link
Copy Source

Goal

Add automated (or semi-automated) checks that continuously audit documentation and READMEs for:

  • Broken internal and external links
  • Terminology consistency (T0–T4, layers vs floors, source of truth)
  • Readability and awkward phrasing
  • Factual drift vs code (wire formats, offload tooling, etc.)

Context

A manual documentation audit was completed in a working session. Findings and applied fixes are recorded on branch docs/improvement under docs/improvement/.

Acceptance criteria

  • Link checker in CI (or scheduled job) for all *.md under docs/, infra/, and root READMEs
  • Glossary anchor validation for #term links
  • Optional readability pass (terminology lint, spell-check US English)
  • Report artifact or PR comment on failure

Out of scope

  • Rewriting design decisions
  • Auto-fix without human review
## Goal Add automated (or semi-automated) checks that continuously audit documentation and READMEs for: - Broken internal and external links - Terminology consistency (T0–T4, layers vs floors, source of truth) - Readability and awkward phrasing - Factual drift vs code (wire formats, offload tooling, etc.) ## Context A manual documentation audit was completed in a working session. Findings and applied fixes are recorded on branch `docs/improvement` under `docs/improvement/`. ## Acceptance criteria - [ ] Link checker in CI (or scheduled job) for all `*.md` under `docs/`, `infra/`, and root READMEs - [ ] Glossary anchor validation for `#term` links - [ ] Optional readability pass (terminology lint, spell-check US English) - [ ] Report artifact or PR comment on failure ## Out of scope - Rewriting design decisions - Auto-fix without human review
eSlider commented 2026-07-10 10:49:12 +01:00
Author
Owner
Copy Link
Copy Source

Documentation audit delivered

Branch docs/improvement → PR #2.

Included: glossary T0–T4, source of truth, link fixes, pose frame alignment, rsync/offload wording, README pass, live demo links, docs/improvement/ audit records.

CI note: first run failed — shallow git clone on default branch could not checkout PR head (fatal: reference is not a tree). Fixed in 9bec50e by git fetch origin ${{ gitea.ref }}. Re-run: verify + Trivy green.

Follow-up for this issue: automate link + glossary anchor checks in CI.

## Documentation audit delivered Branch `docs/improvement` → [PR #2](https://git.produktor.io/eSlider/swarm-house/pulls/2). **Included:** glossary T0–T4, source of truth, link fixes, pose frame alignment, rsync/offload wording, README pass, live demo links, `docs/improvement/` audit records. **CI note:** first run failed — shallow `git clone` on default branch could not checkout PR head (`fatal: reference is not a tree`). Fixed in `9bec50e` by `git fetch origin ${{ gitea.ref }}`. Re-run: verify + Trivy **green**. **Follow-up for this issue:** automate link + glossary anchor checks in CI.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
andrea eSlider (Andrey)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: eSlider/swarm-house#1