Story: Documentation improvements
Table of Contents
This page documents a story in Sprint 25. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
An umbrella story for incremental improvements to ORE Studio's documentation and public-facing site (the org-mode-exported website under `index.org`/`readme.org`/`assets/`). Tasks are added as ideas come up rather than scoping the whole story up front.
Status
| Field | Value |
|---|---|
| State | STARTED |
| Parent sprint | Sprint 25 |
| Now | Not yet started. |
| Waiting on | Nothing. |
| Next | Break the story into tasks. |
| Last touched | 2026-08-11 |
Acceptance
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Scaffold story: Documentation improvements | DONE | 2026-08-04 | 2026-08-04 | Story scaffolding rides this task: documents, sprint wiring, and the scaffold PR. Close it before merging that PR. |
| Add an image carousel to the website homepage | DONE | 2026-08-04 | Initial task for: Documentation improvements | |
| Add systemd unit for site start/stop | DONE | 2026-08-04 | 2026-08-04 | Manage the local site-preview server (compass site serve) as a systemd unit, with proper start/stop commands, instead of ad hoc background processes. |
| Recapture dedicated carousel screenshots | BACKLOG | The carousel's first pass reuses old release screenshots (v0.0.24, v0.0.12, v0.0.15, v0.0.20) as stand-ins for org chart, reference data, compute, and shell – none purpose-built for the carousel. Capture fresh, dedicated composite screenshots (several windows open, current UI/theme) for each carousel topic. | ||
| Consolidate site top navigation | BACKLOG | The site-wide nav (Project/Modeling/Developer/Resources dropdowns) fragments the user journey per external review. Group developer technical specs and model definitions under a unified Docs dropdown. Site-wide change (every page, not just the homepage) via ores-build-site.el's site-html-preamble – deserves its own scoped task/PR, not bolted onto the carousel work. | ||
| Add a quickstart CLI snippet to the homepage | BACKLOG | A short terminal install/quickstart command block on the homepage for fast developer onboarding, per external review. Scope: what the snippet actually shows (git clone + build? a hosted install script?) needs deciding before implementation. | ||
| Add code-review-comments skill | DONE | 2026-08-11 | 2026-08-11 | New Claude Code skill that reviews and cleans code comments, wired into CLAUDE.md so it applies to all code we create or edit. |