Onboarding docs

Onboarding docs

Onboarding documentation is measured by one number: time from "new person" to "made their first useful contribution". Every unexplained step, every setup instruction that fails silently, every piece of tribal knowledge not written down adds days and erodes the newcomer's confidence.

Method

1. Get to a verified working setup, step by step. Exact setup instructions (tested on a clean machine, because yours has years of accumulated state the newcomer's does not: see tutorial-writing's clean-environment testing), with a verification after the critical steps ("run this; you should see X") so failures surface immediately, not three steps later. A setup guide that assumes prior state fails every actual new hire.
2. Automate setup where you can, document the rest. A setup script or dev container (see docker-image- optimization) that does the mechanical steps, with docs explaining what it did and the manual pieces it cannot; the less a human must hand-execute, the fewer ways it breaks. Automated-and-documented beats a twenty-step manual checklist that drifts.
3. Provide a first-contribution path. A curated set of good-first-issues (see community-building, open-source-maintainer-role), a walkthrough of the contribution workflow (branch, PR, review, CI: see branch-strategy, pull-request-size), and the local feedback loop (how to run tests, lint, the app): the newcomer needs a safe small win early, and pointing them at a real change with guardrails delivers it.
4. Write down the tribal knowledge. The context that lives in senior heads: why the architecture is this way (link the vision and ADRs: see technical-vision, architecture-decision-records), the non-obvious conventions, who owns what (see code-owners), where to ask for help. This is the highest-value and most-often- missing onboarding content, because the people who know it forgot they had to learn it.
5. Map the codebase and the workflow. A high-level tour (what lives where, the main flows: see architecture- diagrams at Context/Container level) and the day-to-day rhythm (standups, reviews, releases: see standup, deployment-pipelines): orientation, not exhaustive detail. The newcomer needs a map to explore from, not the whole territory memorized.
6. Let each new hire fix the onboarding. The newest person is the only one who can see what the docs assume and omit; make "improve the onboarding doc" their first task (see boy-scout-rule): this is the mechanism that keeps onboarding current, because it decays exactly as fast as the codebase changes and only fresh eyes catch the drift.

Boundaries

• Onboarding docs get someone productive; they are not comprehensive reference (see docs-information- architecture) and should not try to be, a newcomer drowns in completeness. Orient and launch, link the depth.
• The docs cannot replace human onboarding (a buddy, questions answered: see mentoring-engineers); they reduce the load and cover the mechanical parts so humans spend their time on the judgment parts.
• Setup docs rot faster than most (every dependency and tooling change can break them); the new-hire-fixes-it loop and clean-machine testing are what keep them alive (see docs-maintenance).