Docs: put a real worked example front and center to hook users early

[jbeda]

Problem

The docs make a new reader work through four conceptual pages before they see a real model. The landing page (docs/index.md) opens with an abstract definition and an ASCII workflow diagram; the concrete worked example (docs/05-parking-garage/) sits at position 5 and is listed only third in "Where to start" ("See it all come together"). The payoff — here is an actual domain model, rendered, with diagrams — arrives late.

For a tool whose whole pitch is "you describe concepts and get a validated, rendered model," the fastest way to hook someone is to show them that artifact immediately, and to make it feel real rather than like a teaching toy.

Goal

Lead with the concrete. A first-time visitor should see a real rendered model — entities, a relationship diagram, an invariant or two — within the first screen, ideally next to the short plain-language conversation that produced it. Concept pages stay, but they come after the reader has seen the thing work.

Proposed changes

• Landing page shows the artifact, not just the pitch. Embed a real slice on index.md: a snippet of a rendered *.modelith.md (a couple of entities plus a Mermaid erDiagram) and, ideally, the few lines of conversation that generated it. Keep the workflow diagram, but below the payoff, not above it.
• Promote the worked example up the order. Move it to right after Getting Started (or make an abbreviated version part of the landing), so it is the second thing a reader hits, not the fifth.
• Reorder "Where to start" so "see a real model" is the first entry.

Open question — is the parking garage the right hero?

The ask is to be "as real as possible." A parking garage is a clean teaching domain but reads as a textbook exercise. Worth deciding whether the hero example should be something a developer audience recognizes as a real system they might actually model (an auth/permissions domain, an orders/payments domain, a CI/deploy pipeline). Could keep parking-garage as a secondary example. Decide before doing the reorg, since it changes what gets embedded on the landing.

Constraints for whoever picks this up

• Docs conventions: pages are NN-name.md with title: front matter; renumbering a page changes its published URL, so update inbound links (README, other docs). See docs/_docs-conventions.md.
• CI coupling — do not miss this: docs/05-parking-garage/ is globbed by path in both Taskfile.yml (the EXAMPLES var) and .github/workflows/ci.yml. If the reorg renumbers or moves that directory, update both globs or task lint-models / render-check silently stops checking the example. CLAUDE.md calls this out.
• Anything embedded from a rendered model must stay in sync with its source YAML (the render golden check), so prefer excerpting the committed .md over hand-writing snippets that can drift.

Related

• Audit follow-up Design follow-ups from the pre-OSS audit (7 items, non-blocking) #4, sub-item 4 (the Ticket-as-value-object teaching moment) touches the same flagship example; if the hero example changes, revisit that note.

🤖 Generated with Claude Code