Onboarding Reference¶
Artifact — instantiates Symbolic Convention Governance
The newcomer's on-ramp to a convention — why it exists, how to apply it, where the exceptions hide, and the mistakes first-timers actually make.
An onboarding reference is a teaching artifact that does not define a convention — it transmits an existing one into practice for a specific incoming audience. Its defining idea is pedagogical, not definitional: it takes a rule that already lives in a style guide, codebook, or standard and converts it into absorbed behavior by explaining why the convention exists, walking realistic worked cases and their wrong counterparts, flagging where the exceptions hide, and naming the mistakes newcomers actually make. It is the difference between a convention that is published and one that is followed.
Example¶
A regional newspaper hires four reporters at once. The house style and the desk-status labels — EMBARGOED, HOLD, SPIKED, the dateline format — are all written down somewhere, but the full style guide is 90 pages and no new reporter reads it before their first deadline. The onboarding reference is a six-page artifact that does something different: it teaches the twelve conventions reporters actually trip on, each with a right/wrong pair, a one-line reason, and the single exception that matters (wire copy retains its agency's style verbatim). It explains that HOLD means "ready but timed," while SPIKED means "killed" — a confusion that has published embarrassments before.
By the end of week one, the new reporters file copy that clears the copy desk without a rework loop. The onboarding reference did not decide any of these conventions; it consumed the style guide and turned it into practice for people who had thirty minutes, not thirty hours. Setup to outcome: a documented rule that would otherwise sit unread becomes reliable behavior on the first deadline.
How it works¶
The artifact is audience-scoped and task-ordered: it is organized by what a newcomer does first, not by the taxonomy of the underlying rule, and it deliberately covers the high-friction minority rather than everything. Its core devices are the example / non-example pair (people learn conventions from cases, not definitions), an explicit "common mistakes" list, and a hand-off: for any edge case it points to the authoritative source instead of duplicating it, so it never becomes a competing copy of the rule.
Tuning parameters¶
- Audience specificity — one reference per role versus one for everyone. Role-targeted references teach faster but multiply upkeep.
- Depth vs. breadth — the top-N gotchas or exhaustive coverage. Narrow references get read; exhaustive ones get skimmed.
- Example density — how many worked right/wrong pairs. More cases build intuition but lengthen the artifact.
- Freshness cadence — how often it is re-checked against the underlying convention. The looser this dial, the faster it drifts stale.
- Deferral vs. restatement — how much it hands off to the authoritative source versus copies inline. Restating is convenient but creates a second source of truth.
When it helps, and when it misleads¶
Its strength is closing the tacit-convention-lockout gap: the situation where insiders know what a label means and newcomers are left guessing. A good onboarding reference makes a convention learnable in the time a newcomer actually has, which is often what separates a living convention from a forgotten document.
Its failure mode is the curse of knowledge — the artifact is written by experts who can no longer feel what is non-obvious, so it explains the parts that were never confusing and skips the ones that are.[n1] It also rots: the underlying convention changes and the reference silently teaches the old rule. The classic misuse is letting it grow into a second, contradicting source of truth that quietly overrides the real standard. The guarding discipline is to draft it from real newcomer mistakes, run it past an actual first-timer as an informal comprehension check, and keep it pointed at the authoritative source for anything it does not fully restate.
How it implements the components¶
adoption_path— its signature: it is the structured route from a published rule to daily practice for a defined incoming group.community_of_use— it targets and inducts a specific newcomer segment, bringing them into the community that shares the convention.usage_rule— it conveys correct application and prohibited uses through worked cases and non-examples, teaching the rule rather than merely citing it.
An onboarding reference does not author the convention it teaches (symbolic_convention) — that belongs to definitional documents like the Codebook, Naming Convention, and Symbol Standard; nor does it hold authority to change the convention (revision_governance), which is the Terminology Review Board.
Related¶
- Instantiates: Symbolic Convention Governance — the onboarding reference is the archetype's adoption on-ramp for newcomers.
- Consumes: the convention it teaches, defined elsewhere — a Naming Convention, a Symbol Standard, or a style guide; the onboarding reference relays that rule rather than inventing it.
- Sibling mechanisms: Codebook · Naming Convention · Symbol Standard · Terminology Review Board · Versioned Convention Registry · Linting or Validation Rule · Style Guide · Glossary
Editorial Notes¶
Form Classification¶
Form family: Communication, Facilitation & Learning
Rationale: The newcomer-scoped artifact teaches why a convention exists, how to apply it, its exceptions, and common mistakes through task-ordered examples.
Nearest alternative: Representation, Specification & Plan — It is stored as a reference, but its operative purpose is building newcomer understanding and capability.
Review outcome: Adjudicated after independent review; high confidence.
Origin Attribution¶
Primary origin: Organizational & Management Science
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Knowledge-management and onboarding practice made the reference a durable artifact for transmitting local conventions to newcomers.
Related originating lineages:
- Education & Pedagogy — Instructional design developed novice-facing explanations that combine rationale, worked use, exceptions, and common misconceptions.
- Library & Information Science — Knowledge organization contributes findable, maintained documentation of conventions.
Review resolution: Authoritative-source research resolves the primary-origin disagreement. Onboarding is an organizational socialization practice that informs and guides newcomers; instructional design and reference organization shape the teaching artifact. Origin breadth is limited to formative lineages; present-day applicability is recorded separately as domain_reach=multi_domain.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Researched adjudication after independent review; high confidence.
Sources consulted:
Notes¶
[n1] The curse of knowledge is a documented cognitive bias in which people who know something find it hard to imagine not knowing it, and so systematically misjudge what a novice needs spelled out. It is the reason expert-written onboarding tends to over-explain the obvious and under-explain the genuinely confusing, and why testing the artifact on an actual newcomer is the standard corrective. ↩