The Problem
Readers couldn't tell finished work from speculation. Drafts, notes, and shipped artifacts all looked the same on the site.
We needed a structure that signals — at a glance — that a project is real, scoped, and accountable. Not a manifesto. A receipt.
Acceptance Criteria
What "done" looks like for this format:
✓ Every section has a name a reader can scan for.
✓ Yes/no claims must be verifiable, not editorialized.
✓ Trade-offs section is non-optional.
✓ Retrospective sits BEFORE the outcome, not after.
✗ Word count under 2,000 (still negotiating).
✓ Template renders on .org, .studio, .com, .net.
✓ Same format works for technical AND exploratory studies.
The Stack Decision
We chose Markdown-first authoring with eight named sections enforced in frontmatter. Renders the same on all four pillars.
Markdown-first authoring
Why: Eight named sections enforced in frontmatter. Renders the same on all four pillars. No CMS to maintain; no editor lock-in.
Trade-off: Authors must learn the section grammar before they can publish.
What we rejected and why:
| Option | Why not |
|---|---|
| Custom CMS | Too heavy for a team of four. |
| Notion docs | Export quality is poor; lock-in. |
| Free-form prose | The whole point was to constrain. |
| Google Docs | No web-native publishing path. |
Key Trade-offs
Consistency over flexibility.
| Axis | Gained | Gave up |
|---|---|---|
| Consistency | Format consistency across the archive. | Flexibility on unusual studies. |
| Review speed | Faster reviews — reviewers know where to look. | Authors find the constraint uncomfortable at first. |
| Scannability | AC + Outcome answer most reader questions. | Some pieces don't fit and stay drafts instead of getting published. |
The Build
Wrote the schema. Built three test studies. Iterated on section names twice.
The biggest change: renaming "Lessons Learned" → "What We'd Do Differently." More honest, less corporate. A reader trusts the second one.
CTA logic forks on study type:
- Technical studies point at
.studio(demo) +.com(paid template). - Exploratory studies point at the artifact itself or the next study in series.
What We'd Do Differently
Acceptance Criteria should have been the first section we designed, not the last.
We spent two weeks on hero treatments before realizing the AC checklist is what readers actually scan when they land on a study.
The hero matters. But not first.
The Outcome
What this format ships
One template, four pillar-aware CTAs, and this study as proof of fit.
What it doesn't do yet: verify acceptance criteria automatically (that's the next study), and handle multi-author byline metadata.
What's Next
This study is exploratory type — so the next-step CTA points at the artifact + the next study in the series, not at a demo or paid template.
- Download the schema —
use-case-study.schema.md - Read the next study → Auto-verifying acceptance criteria