Story: Documentation review follow-ups
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
A documentation review of the agile and meta docs surfaced a batch of structural gaps. The biggest: the agile process page jumbles together concepts that deserve their own pages — what a story is (and epics, and sizing), what a task is, and the three sprint phases — leaving readers no single place to learn each concept and recipes nothing precise to link to. Around that sit smaller gaps: document_types.org is one long page rather than a page per type; there is no document explaining what a definition of done is and why task/story/sprint/ version carry one; the process has no outreach step and no demo step at sprint closure; and the product identity page does not point readers at the user manual.
This story delivers the restructure: per-concept pages with agile-domain overviews, the agile process page reduced to an overview and inventory that links them, and the smaller additions woven in.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 19 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-06-05 |
Acceptance
document_types.orgis split into one page per document type (document_type_<type>.org), with the original page remaining as the index linking them.- A definition-of-done document exists explaining the concept and why task, story, sprint, and version documents must carry one; those documents org-roam-link to it.
- The agile process includes an outreach step (LinkedIn post, Twitter/X post, Discord announcement).
- Sprint closure includes creation of the sprint demo as its last step.
- Dedicated pages exist for: story (what a story is, what an epic is, how stories are sized), task, sprint planning, sprint execution, and sprint closure — each opening with an agile-domain overview and then carrying the detail currently in the process page.
- The agile process page is an overview/inventory linking the per-concept pages; story and task pages are linked from the glossary; recipes link directly to the relevant phase page.
- The product identity document links to the user manual for readers looking for usage instructions.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Restructure agile process into per-concept pages | DONE | 2026-06-05 | 2026-06-05 | Story/task/sprint-phase pages with domain overviews; process page becomes overview + inventory; glossary and recipe links. |
| Add demo creation to sprint closure | DONE | 2026-06-05 | 2026-06-05 | Demo as the last step of sprint closure, if not already present. |
| Add outreach step to the agile process | DONE | 2026-06-05 | 2026-06-05 | LinkedIn post, Twitter/X post, Discord announcement. |
| Add a definition-of-done document | DONE | 2026-06-05 | 2026-06-05 | What a DoD is, why task/story/sprint/version must have one; org-roam links from those docs. |
| Split document types into one page per type | DONE | 2026-06-05 | 2026-06-05 | One document_type_<type>.org per type; document_types.org becomes the index. |
| Create a user-facing product roadmap page | DONE | 2026-06-05 | 2026-06-05 | User-facing roadmap.org telling the product story; delegates to versions/milestones/product identity via links; site nav repointed. PR #1076. |
Note: the "Link product identity to the user manual" task moved to the Create a user guide for ores.qt story, which gathers all manual-content work.
Out of scope
- Changing the agile process itself beyond the additions above — this is a documentation restructure, not a process redesign.
- Restructuring recipes or runbooks (only their links are updated).