Keep onboarding docs up to date: your newest hire is the test suite

Most documentation is at least occasionally read by someone who could fix it. Onboarding docs are not. The engineer who could correct the setup guide in four minutes has not read it since their own first week; the person reading it today does not yet know that the staging URL changed, only that the link is dead. Every failure is experienced by someone who assumes the failure is their own fault.

This is why onboarding pages are where tribal knowledge concentrates: the real onboarding becomes a series of Slack questions to whoever answered last time, and the document becomes a monument. The practices below all attack the same root: they route the newcomer's unique knowledge, the fresh list of everything that is broken, back into the docs before it evaporates.

The friction log is a simple contract with every new hire: from the first hour, keep a running list of every step that failed, every instruction that was wrong, and every question you had to ask a human. No judgment, no filtering, just the raw record while the pain is fresh. A week in, the same knowledge is gone; day-1 confusion is unrepeatable data.

The second half of the contract closes the loop: before the first month ends, the new hire ships at least one fix from their own log, a doc edit, a corrected command, a repaired link, with a teammate clearing the way. This does more than patch a page. It teaches, in week one, that docs here are maintained by the people who hit their edges, which is the only culture in which any of this survives.

# Day-1 friction log: <name>, <start date>

Rule: every failed step, wrong instruction, or question you had
to ask a human becomes a row. Close at least one row yourself
with a doc fix before the end of month one.

| # | Doc step                  | What actually happened          | Fixed in   |
|---|---------------------------|---------------------------------|------------|
| 1 | "brew install foo"        | formula is now foo@2            | PR #4812   |
| 2 | Staging URL in wiki       | 404, environment was renamed    | wiki edit  |
| 3 | "ask #platform for a key" | channel archived, now #infra    | PR #4820   |

Onboarding docs are unusual in having a clean outcome metric: the time from a new hire's first day to their first merged pull request. It is cheap to track, hard to game, and sensitive to exactly the failures docs cause, since a newcomer blocked on setup or lost in the system map merges nothing. If the team and the codebase are stable but time-to-first-PR is creeping up cohort over cohort, doc rot is the first suspect.

Reviewing each new hire's friction log against that number tells you where the time went, and turns "our onboarding feels rough" into a ranked fix list. The same evidence feeds the periodic sweep described in the documentation audit checklist, with the onboarding path always audited first because its failures are the most expensive per reader.

One section of the onboarding page can be exempted from decay entirely: the architecture overview. Instead of a pasted screenshot that fossilizes on day one, embed the diagram by URL. A Datadef project shared public serves both an interactive embed for wiki pages and a permanent image URL for Markdown; either way, when the diagram is edited the onboarding page shows the new version within minutes, with no edit to the page itself. The Notion mechanics, embed block versus image block, are covered in embed diagrams in Notion.

Keeping the diagram itself current is a separate, honest step: a person edits it, or an AI agent connected to the Datadef MCP server updates it from the repo as a CI step after architecture-relevant merges. Datadef does not watch the repository; the regeneration is one wired command. But once wired, the newest hire's mental map of the system is built from a picture that matches production, which is worth more than any paragraph on the page.

The friction log fixes what newcomers can see, which is mostly the first two weeks of surface: setup, access, first tasks. Deeper drift, an architecture section describing last year's system, needs the embed pattern or a scheduled audit, because no newcomer can recognize that a wrong page is wrong. And the live embed requires a public Datadef project; for confidential architecture, a re-exported image with a stated refresh cadence is the fallback. What stale onboarding actually costs, in ramp time and early attrition, is quantified in the cost of outdated documentation.

• Tribal knowledge in engineering teams
• The documentation audit checklist
• Embed diagrams in Notion
• The cost of outdated documentation