usm/docs-experience [in-progress]

Overhaul the generated docs site from a spec-dump into a real reading experience — suppress empty templated stubs, surface the real TOGAF deliverables in the nav, widen the layout to use the viewport, rebuild the homepage as navigation, and give the help and technical audiences distinct voices.

Status: in-progress

Why this exists

Strategic review found the docs generators faithfully dump .usm content into VitePress defaults but do not author a reading experience. Around 30 of 127 pages are empty placeholder stubs (including a UI map for a CLI); the real TOGAF detailed-design output exists but is orphaned from the nav; content is squeezed into VitePress's 688px default; the homepage is a layout:home hero with no sidebar plus a README-style metrics dump; and the help/technical audiences differ only by filtering, never by voice. Because usm generate produces this for every consumer (daingerdainger-com and others), every flaw ships to every downstream docs site.

Design decisions

emit-only-when-populated

Decision: Emit a templated page only when its source section is populated; never write a placeholder

Rationale: A placeholder promises depth and delivers nothing — worse than the page not existing. Omission is honest.

togaf-as-architecture-section

Decision: Surface togaf output as the Architecture section of the docs site, not a separate target

Rationale: The detailed design already exists; the failure was discoverability. Wiring it into the nav fixes both the empty stubs and the orphaned output in one move.

css-not-config-for-width

Decision: Widen via generated theme CSS custom properties, not VitePress config knobs

Rationale: CSS custom properties are the documented override path and survive VitePress minor bumps; config knobs for layout do not exist.

feature-cards-as-nav

Decision: Use the VitePress features grid as homepage navigation rather than forcing a sidebar onto layout home

Rationale: Cards are the canonical landing-page nav pattern and keep the hero; forcing a sidebar means abandoning the home layout entirely.

voice-is-render-mode

Decision: Audience is a render mode (voice), not just a filter

Rationale: Filtering alone produced two identical sites; the brief needs two different documents from one source.

How it works

Suppress templated stubs a service has no data for (suppress-stubs)

A service only emits the architecture/ui/deployment/operations/decisions pages its .usm actually populates. A CLI gets no UI map or production-deployment page.

1. Inspect — each templated page generator checks whether the source service carries that section data
2. Omit — skip emitting the page when the section is empty rather than writing a placeholder
3. Prune — the matching sidebar entry is also omitted so nav has no dead links

Surface the real TOGAF deliverables as the Architecture section (surface-togaf)

The togaf generator already produces Phase A-H deliverables; wire them into the dev-docs sidebar as a real Architecture section instead of empty per-service architecture stubs.

1. Generate — togaf output into the docs tree (not a parallel orphaned directory)
2. Wire — sidebar Architecture group with Vision, Business, Data, Application, Technology, Governance links
3. Scope — help audience omits the Architecture section (internal detail)

Widen the layout to use the viewport (widen-layout)

Override VitePress defaults so reference content, tables, code, and diagrams breathe.

1. Set — --vp-layout-max-width and content-container max-width via generated theme CSS
2. Enable — full-width code blocks and tables that break out of the prose column

Rebuild the homepage as navigation (rebuild-homepage)

Drop the README-style metrics/identity dump; keep the hero and add a features grid whose cards ARE the navigation into the docs.

1. Drop — the At-a-glance, Identity, Who-its-for, Next-steps body markdown from index.md
2. Add — a features grid of cards linking to Getting Started, Schema, CLI, MCP, Architecture (dev only)
3. Keep — the hero actions (Get Started, Schema Reference)

Give help and technical audiences distinct voices (audience-voice)

The same feature spec renders differently per audience — task-oriented for help, reference-faithful for technical.

1. Render — help voice leads with when-to-run, example output, troubleshooting, derived from flows and contracts
2. Render — technical voice is the full spec-faithful reference (intent, flows, contracts, tests, decisions)
3. Share — one source .usm file, two render paths

Anti-drift and discoverability (anti-drift)

Pin the getting-started version from package.json and enable VitePress sitemap on both sites.

1. Derive — getting-started install version from package.json, not a hardcoded string
2. Enable — sitemap.hostname in both VitePress configs

Guarantees

no-empty-stubs

No empty placeholder pages are emitted

Acceptance criteria:

• [ ] A templated section page is emitted only when the source service carries data for it
• [ ] Sidebar entries match emitted pages one-to-one (no dead links)
• [ ] A CLI never gets ui, production-deployment, or observability pages

togaf-in-nav

The real TOGAF deliverables are reachable from the technical docs nav

Acceptance criteria:

• [ ] dev-docs sidebar has an Architecture group linking the Phase A-H deliverables
• [ ] help audience omits the Architecture section
• [ ] No parallel orphaned togaf directory

content-width

Reference content uses the viewport, not VitePress's 688px default

Acceptance criteria:

• [ ] --vp-layout-max-width overridden to ~1280 or wider
• [ ] Code blocks and tables render full-width
• [ ] Applies to every consumer site on their next generate

homepage-is-navigation

The homepage is a navigation surface, not a metrics dump

Acceptance criteria:

• [ ] No At-a-glance, Identity, or Who-its-for body markdown on index.md
• [ ] A features grid of cards links into the primary doc sections
• [ ] Hero actions retained

audience-voice-distinct

Help and technical audiences read differently for the same feature

Acceptance criteria:

• [ ] Help feature page leads with when-to-run and example output
• [ ] Technical feature page is spec-faithful (full flows, contracts, tests)
• [ ] Same source .usm, two render paths

no-handwritten-drift

No hand-written drift in generated docs

Acceptance criteria:

• [ ] getting-started install version derived from package.json
• [ ] VitePress sitemap enabled on both audiences

Implementation

• Test code status: none

See Also

• usm/gen-markdown
• usm/gen-togaf
• usm/cli-docs