[Deep Dive #41] Glossary Contract Atlas - discussion
Deep Dive #41 is surprisingly practical: it treats the Glossary as a contract atlas, not a dictionary. Instead of arguing which router is "real", it recommends maintaining shared file-router + component-router terminology and making the terms show up in code review language and rendered evidence so the vocabulary is usable, not trivia.
Do you keep a glossary in the repo (and treat it like an API surface), or rely on tribal knowledge? How do you stop 'two router systems' from becoming a permanent source of confusion for new teammates? What glossary terms do you render in the UI as evidence (route id, lane names, posture key) so support/debugging can speak the same language?
Comments (10)
Back to latestWe added a short glossary file to our repo and it reduced 'what do you mean by shell' debates instantly.
It's not about being pedantic, it's about preventing silent mismatches.
The docs glossary is underrated. Linking to it in PRs is an easy way to keep vocabulary aligned without writing essays.
Related: Glossary.
Two router systems is fine if you treat it as 'two maps' with explicit signage.
The failure mode is pretending you have one map and then surprising people with exceptions.
Rendering glossary evidence sounds silly until you work support. A route id + posture key in the footer can save hours.
If the deep dives are going to name things (vault, lanes, shell), we should make those names visible.
The 'contract atlas' framing matches the next post on release notes: words are part of the migration story.
If the language changes, the upgrade path changes.
We put a glossary link right in our app shell (dev-only) and it helped onboarding more than any architecture diagram.
Glossary + screenshots = shared reality.
We literally render a tiny "atlas strip" at the bottom of internal builds:
tsx
return (
<footer data-shell={shellId} data-route={routeId} data-lane={lane} data-posture={posture}>
<a href="/docs/glossary">glossary</a>
</footer>
);It feels dumb until you realize every bug report now includes the vocabulary keys you need.
Counterpoint: glossaries can become bikeshedding magnets.
If people argue for hours about definitions, the atlas becomes politics instead of a tool.
True, but I think the post's move is to make terms enforceable: a term isn't "real" until it's a rendered marker or a contract key.
That shifts debate from vibes to "what does this term let us debug or migrate".
Yeah, if the term has to show up in the UI, it gets a lot harder to bikeshed endlessly.
The atlas framing also helps with migrations: you can change implementation while keeping the vocabulary stable.
New hires learn "shell/scope/lane" once, and the codebase can evolve underneath without re-teaching everything.
A practical rule: every glossary term should have one "evidence" example.
If you can't show what it looks like rendered (data attrs, ledger field), it probably isn't a useful term yet.