[story #52] UX: operator-tutorial readability spec + revised outline #98

2026-06-10T15:30:21Z

ux-designer commented

2026-06-10 15:30:21 +00:00

Story #52

Traces to: Epic #31 → INTV-1 #27 → umbrella #26 → Pillar I gate PR #25 → Pillar II gate PR #45 → Goal 2 (operator tooling).

Design bundle: docs/design/operator-tutorial-readability-spec.md (in-repo artifact)

Accessibility: WCAG 2.1 Level AA — heading hierarchy (no skipped levels), descriptive link text (no bare URLs, no "click here"), screen reader navigable (TOC + headings), keyboard accessible (static Markdown, no JS required), plain-text fallback (all cross-references include file paths as readable text), copy-paste command blocks with $ prompt prefix and "Expected output" labels.

Design tokens: None — this is a Markdown document inheriting Gitea's default rendering. No new visual patterns introduced.

What this PR contains

docs/design/operator-tutorial-readability-spec.md — UX readability and accessibility spec:
- Acceptance-criteria traceability (AC-1..AC-3)
- Cross-reference table mapping every operator tool (REQ-INB-40..-59) to its first mention and link target
- Readability spec (Flesch-Kincaid grade 10, 2nd person imperative, jargon gates)
- Accessibility spec (WCAG 2.1 AA, heading hierarchy, link text, screen reader, keyboard, plain-text fallback)
- Revised doc outline with structural blueprint
- Verification plan
docs/operator-tutorial.md — revised tutorial implementing the spec:
- Recovery shortcut block at document top (AC-3: less than 5 min recovery for returning operator)
- Bold Goal / Next lines per chapter
- Descriptive link text (tool names, not bare URLs or click here)
- Consistent cross-references to all operator tools (AC-2)
- Anchor links for in-page navigation

Blocked dependencies

This PR ships the preliminary UX/technical-writing work as directed by the CTO. Exact command references for S-A1 (#51) and S-C1..C4 (#54, #61, #59, #58) will be updated when those upstream Stories reach done. The current outline uses the TRD-specified command syntax as placeholders.

Out of scope

Dashboard views (Epic #32) — referenced, not authored
Recovery tools (Epic #33) — referenced, not authored
Container hardening (INTV-2 D) — referenced, not authored

Reviewer: @cto-ciagent

Pillar III gate for Story #52. Merge into release/v1. Comments are append-only.

## Story #52 **Traces to:** Epic #31 → INTV-1 #27 → umbrella #26 → Pillar I gate PR #25 → Pillar II gate PR #45 → Goal 2 (operator tooling). **Design bundle:** `docs/design/operator-tutorial-readability-spec.md` (in-repo artifact) **Accessibility:** WCAG 2.1 Level AA — heading hierarchy (no skipped levels), descriptive link text (no bare URLs, no "click here"), screen reader navigable (TOC + headings), keyboard accessible (static Markdown, no JS required), plain-text fallback (all cross-references include file paths as readable text), copy-paste command blocks with `$ ` prompt prefix and "Expected output" labels. **Design tokens:** None — this is a Markdown document inheriting Gitea's default rendering. No new visual patterns introduced. ### What this PR contains 1. **`docs/design/operator-tutorial-readability-spec.md`** — UX readability and accessibility spec: - Acceptance-criteria traceability (AC-1..AC-3) - Cross-reference table mapping every operator tool (REQ-INB-40..-59) to its first mention and link target - Readability spec (Flesch-Kincaid grade 10, 2nd person imperative, jargon gates) - Accessibility spec (WCAG 2.1 AA, heading hierarchy, link text, screen reader, keyboard, plain-text fallback) - Revised doc outline with structural blueprint - Verification plan 2. **`docs/operator-tutorial.md`** — revised tutorial implementing the spec: - Recovery shortcut block at document top (AC-3: less than 5 min recovery for returning operator) - Bold Goal / Next lines per chapter - Descriptive link text (tool names, not bare URLs or click here) - Consistent cross-references to all operator tools (AC-2) - Anchor links for in-page navigation ### Blocked dependencies This PR ships the preliminary UX/technical-writing work as directed by the CTO. Exact command references for S-A1 (#51) and S-C1..C4 (#54, #61, #59, #58) will be updated when those upstream Stories reach done. The current outline uses the TRD-specified command syntax as placeholders. ### Out of scope - Dashboard views (Epic #32) — referenced, not authored - Recovery tools (Epic #33) — referenced, not authored - Container hardening (INTV-2 D) — referenced, not authored **Reviewer:** @cto-ciagent --- *Pillar III gate for Story #52. Merge into release/v1. Comments are append-only.*

ux-designer added 1 commit 2026-06-10 15:30:21 +00:00

[story #52 ] UX: operator-tutorial readability spec + revised outline 07831d26d0

- Add docs/design/operator-tutorial-readability-spec.md with:
  - Acceptance-criteria traceability (AC-1..AC-3)
  - Cross-reference table mapping every operator tool to REQ and link
  - Readability spec (Flesch-Kincaid ≤10, 2nd person, jargon gates)
  - Accessibility spec (WCAG 2.1 AA, heading hierarchy, link text,
    screen reader notes, keyboard navigation, plain-text fallback)
  - Verification plan

- Update docs/operator-tutorial.md with:
  - Recovery shortcut block at top (AC-3: <5 min recovery)
  - Bold Goal/Next lines per chapter
  - Descriptive link text (no bare URLs, no 'click here')
  - Consistent cross-references to all operator tools (AC-2)
  - Anchor links for in-page navigation

Co-Authored-By: Paperclip <noreply@paperclip.ing>

ux-designer requested review from cto-ciagent 2026-06-10 15:30:30 +00:00

ux-designer referenced this pull request

2026-06-10 15:31:03 +00:00

[story] S-A2: docs/operator-tutorial.md — single point-of-entry for the operator (REQ-INB-53) #52

grimacing merged commit dff35e2a78 into release/v1

2026-06-10 15:35:16 +00:00

grimacing deleted branch ux/story-52-operator-tutorial

2026-06-10 15:35:17 +00:00

cto-ciagent referenced this pull request

2026-06-15 20:32:56 +00:00

MAJOR v1 — InboxOS Strategic Roadmap #99

Sign in to join this conversation.