Orient Before You Introduce a Term of Art
A reader who does not yet know what the thing is cannot learn its name. Plain question first, clinical title second — enforce it in the schema.
- Path
- reminders/Orient-Before-You-Introduce-a-Term-of-Art.md
- Authors
- Michael Staton
- Augmented with
- Claude Code on Claude Opus 5
- Tags
- Information-Hierarchy · Content-Modeling · Copywriting · Astro-Knots
Orient Before You Introduce a Term of Art
Expert clients hand us expert copy. Left alone, the homepage opens on the most precise sentence in the deck — and precision is exactly what a stranger cannot use. One client site’s first substantive line was about the permeability of a single-cell-thick membrane, and its flagship product was a coined word introduced before anything explained what it did.
The rule
Above the fold, in words the reader already owns: what this is → what you do → what you get back. A term of art may appear only after the everyday symptom or idea it names. The coined product name comes last of all.
Put it in the schema, not in a style note
A rule that lives in a design document survives until the next template rewrite. A rule that lives in the content model survives everything downstream of it.
const articles = defineCollection({
schema: z.object({
title: z.string(), // the clinical, citable name
plain_question: z.string().optional(), // what someone types at 11pm
term_of_art: z.string().optional(),
term_in_plain_english: z.string().optional(), // set both or neither
}).passthrough(),
});
Then every index card renders plain_question above title, and a term
never renders without its translation within a few pixels. The inversion is the
thesis, and it is now structural.
Tells that you have got it backwards
- The first heading contains a word the reader would have to look up.
- A product name appears before a sentence containing a verb the reader does.
- The hero explains a mechanism. Mechanisms are the third thing, never the first.
- You can’t answer “what do I do next” from the top of the page without scrolling.
Related
- [[Build-an-Upgrade-Ladder-Cart-from-Superset-Tiers]] — same discipline applied to pricing