Story: Clear component documentation debt
Table of Contents
This page documents a story in Sprint 19. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
validate_docs.sh reports seventeen violations, all pre-existing
documentation debt at the component group level of split
components: the per-part overviews (e.g. ores.dq/api/modeling/) are
fine, but the group-level projects/ores.X/modeling/ doc is missing,
skeletal, or lacks a diagram. Clear the debt so the validator runs
clean, and reconcile the contradiction between the validator (which
demands group-level docs) and the create-component runbook (which
calls the group-level overview "optional").
The violations as of 2026-06-05:
| Violation | Meaning | Components |
|---|---|---|
MISSING_OVERVIEW |
no group-level modeling/component_overview.org |
analytics, dq, iam, refdata, scheduler, workspace |
MISSING_SECTION |
group overview exists but skeleton sections unfilled (Inputs, Outputs, Entry points, Dependencies, See also) | compute, controller, reporting, trading, workflow |
MISSING_PUML |
no group-level diagram in modeling/ |
compute, controller, reporting, seeder, trading, workflow |
Status
| Field | Value |
|---|---|
| State | BACKLOG |
| Parent sprint | Sprint 19 |
| Now | Not yet started. |
| Waiting on | Nothing. |
| Next | Pick up the violations task. |
| Last touched | 2026-06-05 |
Acceptance
validate_docs.shreports zero violations.- Every new group-level overview has real content per the Component Documentation Guide — summary, inputs, outputs, entry points, dependencies and see-also links — not placeholder text.
- Group-level PlantUML diagrams exist for the flagged components and render via the diagram pipeline.
- The create-component runbook and the validator agree on whether the group-level overview is required; whichever way the decision goes, the loser is amended.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Fix the seventeen validate_docs violations | BACKLOG | Write the six missing group overviews, fill the five skeletal ones, add the six missing pumls; reconcile validator vs runbook. |
Decisions
Out of scope
- Per-part overviews (api/core/service) — these are already in place and validating.