Written onboarding paths

A written onboarding path is a structured, step-by-step guide that takes a new engineer from zero access to productive contribution on a specific codebase or team.

·Documentation refresh initiative is active with measurable progress
·Architecture Decision Records (ADRs) are written for significant technical decisions
·Written onboarding path exists (new developer can self-serve key setup steps)

·ADRs are indexed and searchable
·Onboarding path has been validated by at least one new hire completing it solo

Evidence

·Documentation refresh tracking (issues, PRs, completion percentage)
·ADR directory in repository with recent entries
·Written onboarding guide with step-by-step instructions

What It Is

A written onboarding path is a structured, step-by-step guide that takes a new engineer from zero access to productive contribution on a specific codebase or team. It is not a README. It is not a list of links. It is a sequential path with clear milestones: set up your environment, run the tests, make your first change, understand the deployment process, read the three most important ADRs, shadow an on-call rotation. Each step has a success condition. Each step is tested against new engineers regularly enough to catch drift.

The critical difference between a written onboarding path and typical onboarding documentation is specificity. "Get familiar with the codebase" is not a step. "Read src/services/auth/ and be able to explain the session validation flow to your buddy" is a step. The specificity is what makes it possible to verify completion, measure time, and improve the path systematically.

Written onboarding paths matter doubly in AI-augmented development environments. When agents are part of the development workflow, onboarding must cover not just how the codebase works but how to work effectively with the AI tooling the team uses: which tools, which prompts work well, which contexts to provide, what the agent cannot be trusted to do autonomously. This "agent onboarding" is invisible in most organizations — every engineer figures it out independently — which means onboarding time and effectiveness vary wildly.

At L2, written onboarding paths exist in some form but are maintained inconsistently. They were written when the team was founded or when someone found the pain acute enough to address, and they have drifted from reality as the codebase evolved. The path to L3 is making onboarding path maintenance a first-class responsibility, tied to every significant change in the development environment.

Why It Matters

Onboarding time is directly measurable - a written path with milestones makes it possible to track time-to-first-PR and time-to-independent-contribution, creating a metric that improves as the path improves
Agents need onboarding context too - a well-written onboarding path stored in the repository gives agents access to the same structured understanding of the codebase that it gives new humans; an agent asked to "help onboard a new engineer" can actually follow the path
Inconsistent onboarding creates inconsistent engineers - without a written path, onboarding quality depends entirely on which senior happens to be the buddy; some engineers learn patterns and constraints that others miss, creating uneven code quality months later
Written paths surface documentation gaps - every step in an onboarding path that says "ask a senior" is a documentation gap; making the path explicit makes the gaps visible and prioritizable
Paths reduce senior interrupt load - each question answered by the written path is a question that doesn't interrupt a senior engineer; at scale, good onboarding documentation is one of the highest-leverage investments a team can make

Getting Started

Map the current onboarding experience - ask a recent onboardee to reconstruct their first week from memory: what they did, in what order, where they got stuck, who they asked. This is your current de facto onboarding path. Write it down exactly as it happens, not as you wish it happened.
Structure it into phases with milestones - group the steps into phases: Environment Setup (day 1), First Contribution (week 1), Independent Contribution (month 1), Full Context (month 3). Each phase should have a clear goal and a verification step that confirms the goal was achieved.
Test it against a new hire - have the next new engineer follow the written path literally, with a senior watching silently. Every place they get stuck is a gap in the path. Update the path immediately after each onboarding cycle, not at a quarterly doc sprint.
Add an "AI tooling" section - document which AI tools the team uses, how to configure them, which prompts and workflows have proven effective, and what the agent cannot be trusted to do unsupervised. This section requires input from Victor and the engineers who use AI tools daily.
Version the path with the codebase - store the onboarding path in the repository. When a PR changes the development environment, the CI pipeline should flag if the onboarding path was not updated. Make path maintenance a requirement in the PR template for environment changes.
Measure and iterate - track time-to-first-PR and time-to-independent-contribution for each new hire. Track which steps in the path take longest. Each metric is a prioritized improvement target.

Tip

Write the onboarding path for the engineer you want to onboard, not the engineer you have. If your path assumes familiarity with your internal tools, it will fail for external hires. The path should stand alone without requiring a buddy to interpret it.

6 steps to get from here to the next level

Common Pitfalls

Writing the path once and never updating it. An onboarding path written six months ago may describe a development environment that no longer exists, tools that have been replaced, and processes that have changed. A drifted path is worse than no path — it sends new engineers down dead ends with apparent authority. Paths must be updated as part of every significant environment change, not as a periodic cleanup exercise.

Confusing a link list with a path. A document that lists ten links to wikis, READMEs, and internal tools is not an onboarding path. A path has sequence, dependency, and verification. Step 3 should depend on completing step 2. Each step should have a way to confirm it was done correctly. Links are inputs to steps, not steps themselves.

Making it too long. A 50-step onboarding path that covers every detail of the organization will not be read. The goal is the minimum path to productive contribution, not a comprehensive encyclopedia. Depth should be available through links, not embedded in the primary sequence. If the path takes more than two days to complete, it is too long.

Not covering the "why." A path that says "run make setup" without explaining what it does leaves engineers unable to debug when it fails. Each step should include just enough context to make the step comprehensible, and a pointer to deeper documentation for engineers who want to understand more.

Assuming the buddy will fill the gaps. Onboarding buddies are a valuable complement to written paths, but they should not be a substitute for documentation gaps. If the path requires a buddy to interpret, the path is incomplete. Buddies should be available for questions that the path does not anticipate, not for questions the path should have answered.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob's onboarding process is inconsistent. Engineers onboarded by his best seniors become productive in six weeks. Engineers onboarded without close guidance take three months or more. He cannot identify the difference because he does not have a written path to compare against — each senior onboards differently, and there is no standard to measure against. He has no metric for onboarding effectiveness and no way to improve it systematically.

Bob should commission a written onboarding path as a team-owned artifact, with a named owner for each team's path and a quarterly review cycle. He should track time-to-first-PR for every new hire and use the variance in that metric to identify which teams have stronger paths. The goal is to make onboarding quality independent of which senior happens to be available — to encode the best practices of his best onboarders into a document that every new hire can access equally. Once the path exists, Bob should also ensure it covers AI tooling, because an engineer who does not know how to use the team's AI tools is operating at a disadvantage from day one.

SarahProductivity Lead

Sarah has been trying to measure onboarding effectiveness for years, but without a standard path, she has no consistent unit of measurement. Every new hire has a different experience, learns different things, and reaches productivity at different rates. She cannot tell whether a slow onboarding was due to a gap in the path, a lack of buddy availability, or inherent complexity in the domain. Everything is confounded.

A written onboarding path gives Sarah the standardization she needs to measure effectively. Once the path exists, she can track step completion times, identify which steps consistently take longer than expected, and use that data to prioritize improvements. She should also run periodic path audits — having a recent onboardee review the path and flag steps that no longer match reality. This feedback loop is the most reliable way to keep the path current without requiring seniors to proactively maintain it.

VictorStaff Engineer - AI Champion

Victor sees two opportunities in written onboarding paths. First, a path stored in the repository is context an agent can use. When an agent is helping a new engineer understand the codebase, it can reference the onboarding path to give structured guidance rather than ad-hoc answers. Second, the process of writing the onboarding path surfaces documentation gaps that block agents as much as they block humans — if the path has to say "ask a senior," that knowledge should be in documentation that the agent can access.

Victor should champion adding an "AI tooling" section to every team's onboarding path. This section should cover which agents and tools the team uses, how to configure them correctly, which prompts are effective for common tasks, and what to do when an agent produces output that seems wrong. He should gather this knowledge from the engineers who use AI tools daily and keep it current as the tooling evolves. An engineer who arrives knowing how to work with the team's AI setup is a week ahead of one who has to figure it out independently.