The developer onboarding program decision record: why the ramp structure model you chose determines your time-to-first-contribution floor and your documentation freshness decay surface

A 29-person B2B SaaS company built a procurement workflow platform for mid-market professional services firms. The company had grown from 6 to 29 engineers over 24 months after a successful Series A. The founding team had been together since the beginning — they had shared context, a common understanding of the codebase's architecture, and a collective memory of every significant decision made in the system's first two years. That collective memory was not written down anywhere in a form a new engineer could use. The architecture lived in the founding team's heads. The development environment setup was a set of steps one of the founding engineers had written in a Notion page two years prior and had not revisited since. The database seeding instructions referenced a Docker configuration that had been replaced seven months ago. The local authentication setup referenced a development identity provider that had been migrated to a new provider in the same period. The Notion page's last-edited timestamp was 22 months ago.

In month 25 of the company's life, the VP Engineering hired a senior backend engineer from a well-regarded competitor. The engineer had 7 years of experience, strong Rails proficiency, and domain knowledge that was directly relevant to the product. She was exactly the hire the company needed. Her first day included a company overview from the CEO, access provisioning from the engineering manager, an introduction to the team, and a message from a collegial senior engineer who had been informally designated as her point of contact: "feel free to ping me whenever you're stuck." The Notion onboarding page was shared with her. No one told her how much of it was still accurate. No structured first-week agenda existed. The assumption, unspoken and unexamined, was that a senior engineer with her experience level would find her way through the codebase with minimal handholding — an assumption that was correct in the abstract but failed to account for the specific friction of an onboarding environment that required debugging stale instructions before it was possible to run the application locally.

She spent day 1 and day 2 following the Notion setup guide. The Docker configuration referenced a service that no longer existed. She pinged the senior engineer point of contact, who was in a planning meeting and replied 4 hours later with a Slack message pointing to a GitHub issue from 7 months ago where the migration had been discussed. The new configuration was in that issue, not in the Notion page. She updated her local setup. On day 3, the authentication setup failed — the development identity provider had a new client ID that was not in the documented environment variables. Another Slack message. The correct client ID was in a 1Password vault she had not been provisioned access to. Provisioning required an email to the security team, who responded the next business day. Day 5 arrived and she had not successfully run the application locally. By day 7 she had the application running. The founding engineer who had been her informal point of contact was in a sprint crunch and had not followed up proactively after the initial access issue. She began exploring the codebase independently. She found no architectural overview, no decision log, no explanation of why the data model was structured the way it was, and no documentation that distinguished between the current system and the legacy paths that were no longer exercised but had not been deleted. The first PR she opened was in week 4: a refactoring of a utility function she had identified after enough codebase exploration to feel confident about a small, bounded change. It was merged. Her first feature contribution — a new workflow step in a moderately complex part of the codebase — came in week 9. She was a senior engineer with directly relevant experience. The 9-week ramp was not a reflection of her capability. It was a reflection of a ramp structure that had not been designed. Connect this to the engineering hiring process decision record: the hiring process and the onboarding program are sequential decisions whose consequences are entangled — a hiring process that selects for senior engineers with directly relevant experience can tolerate a longer ramp time without losing productivity, but only if the ramp structure is designed for engineers at that level; an unstructured onboarding that would be navigable by a highly self-directed senior engineer in week 3 is still an unstructured onboarding that depends entirely on the individual engineer's resilience, and teams that hire senior engineers and skip onboarding structure are making a bet that their hiring accuracy is high enough that every new hire will succeed despite the lack of structure — a bet that becomes expensive the first time a strong hire fails to ramp because the environment setup documentation was stale and they chose to leave rather than debug infrastructure they did not build.

A 44-person developer tools company built a static analysis and code quality platform for enterprise engineering teams. They had been operating a buddy program for 18 months. The program had been introduced after two new hires in the company's early days had expressed dissatisfaction with their onboarding experience in exit interviews — both engineers had left within 8 months, and the retroactive analysis identified onboarding as a contributing factor. The VP Engineering had proposed the buddy program as the fix: every new engineer would be paired with an experienced engineer from their team who would serve as their primary resource for questions, context, and guidance through the first 30 days. The program was announced via a company Slack message, the engineering manager assigned buddies at the time of each new hire, and the buddy was notified via a direct message: "you'll be [new hire]'s buddy — they start Monday." No further structure was defined. No time budget was allocated. No responsibilities were specified. The expectation, reasonable in isolation, was that experienced engineers would know how to mentor and would allocate the time it required.

Over the following 6 months, 8 engineers were hired. Their time-to-first-contribution ranged from 3 weeks to 14 weeks. The fastest ramp was an engineer paired with a senior engineer who had joined the company two years prior, had experienced a poor onboarding herself, and had developed a personal methodology for buddy work: she blocked 2 hours per day for the first week to do paired programming with new engineers, she scheduled a 30-minute daily check-in for the first 10 business days, she had a document she shared with each new hire outlining the codebase's 5 highest-complexity areas and why each was complex, and she provided line-by-line code review on their first 5 PRs with commentary focused on team conventions rather than correctness. The engineer she buddied reached first contribution in week 3. The slowest ramp was an engineer paired with a strong senior engineer who was carrying the lead implementation role on a major feature delivery during the month the new hire joined. The buddy sent a welcome message on day 1 and replied to Slack messages within a few hours, but did not initiate contact, did not schedule check-ins, and was not in a position to reduce his sprint commitment to create space for buddy work because the feature deadline was external and fixed. The new engineer — a mid-level engineer who had not previously worked in the codebase's primary language at a production scale — spent weeks 1 through 6 reading code, attempting to understand the architecture independently, and opening small PRs in the testing framework that were low-risk but also low-contribution. Her first meaningful feature contribution came in week 14 after a 1:1 with the VP Engineering at week 8 that identified the buddy relationship had not been providing the support she needed and reassigned her to a different senior engineer as a second-chance mentor. The variance across the 8-hire cohort was not a variance in individual capability or experience level. Three of the four longest ramp times corresponded to buddies who had been assigned at a time when they were carrying significant sprint commitments. The buddy model had been designed to improve on the previous no-structure approach, and it had — the average ramp time decreased from 11 weeks to 7 weeks — but the variance revealed that the program's quality was a function of buddy allocation and personality, not of the program's structure. Connect this to the developer experience decision record: the buddy program is an investment in developer experience at the highest-impact moment — the point when an engineer's perception of the team's culture, code quality, and collaborative norms is being formed — and like all developer experience investments, its return depends on whether the investment is structural (a defined time budget, responsibilities, and cadence that produce a consistent minimum experience regardless of which buddy is assigned) or individual (relying on motivated individuals to fill the structural gap); a developer experience investment that depends on individual motivation will produce high variance outcomes and will degrade over time as the motivated individuals' priorities shift, and the degradation will not be visible in the average metric until several cohorts of new hires have experienced the below-average version of the program.

The VP Engineering ran a structured retrospective at month 6 with the 8 new hires. Six of the eight reported that they had found their onboarding experience adequate or better. Two reported that it had been inadequate. The VP read the data as 75% satisfaction and concluded the program was working. A different analysis of the same data — pairing each engineer's retrospective response with their time-to-first-contribution — revealed that the two engineers who reported inadequate onboarding were the same engineers whose ramp had taken 14 and 12 weeks respectively, and that both had been paired with buddies who had been at capacity during the onboarding period. The relationship between buddy availability and ramp time was not visible in the aggregate satisfaction metric. It became visible only when the satisfaction data was joined with the ramp-time data — a query that required logging ramp time for each engineer, which the team had not been doing systematically. The VP began logging it for subsequent cohorts. The data from the next two cohorts confirmed the pattern: ramp time and buddy sprint load at the time of hire were correlated, and the average ramp time masked a bimodal distribution. Connect this to the engineering metrics decision record: the metrics collected for onboarding quality determine what the program can learn about itself; a program that measures only average ramp time and aggregate satisfaction scores will optimize for those metrics, which are sensitive to the highest and lowest performers in each cohort but not to the structural factors that produce variance; adding the per-engineer ramp time log and joining it with the buddy's sprint load at the time of hire reveals the structural signal that the aggregate metrics obscure.

A 36-person SaaS company built a contract lifecycle management platform. In their third year of operation, they had experienced two consecutive bad onboarding cohorts: a senior engineer who had taken 14 weeks to ramp before resigning, and a mid-level engineer who was still not independently productive at week 10. Both experiences were traced in retrospective to the same root cause: no structured onboarding documentation, no defined ramp path, and no systematic support structure. The engineering manager and the VP Engineering decided to fix this properly. They allocated three weeks for the most experienced engineer on the team — a founding engineer who had built the core data model and most of the billing infrastructure — to write a comprehensive onboarding runbook. The founding engineer took the task seriously. He wrote 47 pages of documentation: a development environment setup guide for macOS and Linux, covering every service dependency with exact version numbers and configuration values; an architecture overview with annotated diagrams explaining the six major system components and their data flow; a codebase tour identifying the 12 most important files for a new engineer to understand and explaining what each one does; a local database seeding guide with step-by-step instructions for generating realistic test data; an explanation of the CI/CD pipeline and how to interpret its output; and a first-week checklist with day-by-day tasks for the first 10 working days. The first two engineers to use the new runbook ramped in 4 weeks and 5 weeks respectively. Both gave the runbook high marks in their retrospectives. The VP Engineering was satisfied. The runbook was declared finished and a success.

Eighteen months later, the team had grown to 36 engineers and was hiring aggressively. A new cohort of 4 engineers started in the same month. All four used the onboarding runbook. Of the 47 documented setup steps, approximately 18 no longer worked as written. The Docker configuration in step 3 referenced a service that had been replaced by a managed cloud service 11 months prior. The database seeding instructions in step 12 referenced a script that had been refactored and moved to a different path. The environment variables in step 7 included three variables that were now managed by Vault rather than by a local .env file, and the Vault setup instructions did not exist because Vault had been adopted after the runbook was written. The local authentication setup referenced a development Okta application that had been decommissioned when the company migrated their identity provider. The CI/CD pipeline explanation described a Jenkins configuration that had been replaced with GitHub Actions 8 months prior. Each new engineer hit broken steps and took one of two paths: they pinged a senior engineer for help (adding interruption load to the senior engineers who were in sprint mode) or they spent time debugging the discrepancy between the documented step and the current system state (adding untracked debugging time to their own ramp). The four engineers in this cohort ramped in 6, 8, 11, and 13 weeks. The runbook had not degraded evenly: the architecture overview and the codebase tour were still largely accurate because the architectural decisions were stable; the setup and environment sections had degraded substantially because they were sensitive to specific version numbers, tool paths, and configuration values that changed with routine infrastructure work.

The root cause was not that the runbook had been written poorly. It had been written very well. The root cause was that no one owned its accuracy between cohorts. The founding engineer who wrote it had moved to a different project. Infrastructure changes — service migrations, tool replacements, Vault adoption — were not communicated to anyone responsible for the onboarding documentation because there was no one responsible for the onboarding documentation. Each infrastructure team that made a change had a complete understanding of what they had changed and why, and each team had updated the internal documentation for their specific system. None of them had reviewed whether the onboarding runbook referenced the system they had just changed, because the onboarding runbook was not in their system's documentation. The runbook was a standalone document with no structural connection to the systems it documented, and the structural connection that would have triggered updates — a process that required infrastructure change authors to check whether the onboarding runbook referenced the changed system — did not exist. Connect this to the documentation strategy decision record: the onboarding runbook is a special case of the documentation strategy's most difficult problem — documentation written at a specific point in time that must stay accurate despite describing a system that evolves continuously; the documentation strategy decisions that matter most for onboarding documentation are not the decisions about how to write the documentation but the decisions about how to keep it accurate — who owns the accuracy, what triggers a review, how the runbook is structurally connected to the systems it documents so that a change in one of those systems creates a visible obligation to update the documentation rather than relying on the change author to remember that a runbook exists and to check whether it references their system.

Structural properties set by the developer onboarding program decision

Three structural properties are determined by the founding decisions about ramp structure, documentation ownership, and support model design. None of these properties are visible in quarterly headcount reports or hiring velocity dashboards. They are set when the onboarding program is established and become visible at the first engineering health review that measures time-to-first-contribution, at the first retrospective that joins ramp time data with buddy allocation data, and at the first large cohort that discovers 40% of the setup instructions no longer work.

Property 1: The time-to-first-contribution floor and the ramp path length problem. The time-to-first-contribution floor is the minimum number of days from first day to first production-grade code merged that any new engineer can achieve, regardless of their experience level or self-direction, set by the sequential dependencies in the ramp path. The floor is not the average ramp time (which reflects the distribution of engineer capability and buddy quality across the cohort) but the structural minimum — the minimum path length for an ideal new hire with directly relevant experience, a functional development environment, immediate access to all required systems, an attentive buddy, and no competing sprint work competing for the buddy's attention. The floor is determined by how many sequential steps exist in the ramp path: environment setup (which cannot start until access is provisioned), codebase orientation (which cannot start until the environment runs), first task selection (which requires enough codebase understanding to identify a task that is scoped appropriately for a new hire), and first PR cycle (which requires familiarity with the team's code review process and the CI system). On a well-designed ramp, these sequential dependencies produce a floor of approximately 10 to 14 days for a senior engineer. On an undesigned ramp — stale documentation, access provisioning delays, no structured codebase orientation, first task assignment left to the new engineer — the floor is longer by however many days the debugging and orientation take, and the ceiling is high enough that 14-week ramps are common. The floor is structural and not a reflection of individual engineer quality, which is why measuring it correctly requires logging ramp time for every hire and examining the distribution rather than the average — the floor is visible in the minimum value of the distribution, not in the mean, and a team that measures only the mean will not know whether their best-case ramp is 3 weeks (a structural floor that could be reduced) or 3 weeks (a structural floor that is already near its minimum). Connect this property to the engineering team growth decision record: the time-to-first-contribution floor is a compounding property as the team grows — a floor of 14 days on a 6-person team hiring one engineer produces 14 days of lost productivity per hire; a floor of 14 days on a 30-person team hiring 8 engineers per quarter produces 112 days of lost productivity per quarter from the floor alone, before accounting for above-floor ramp variance; the growth decision that extends the team size without extending the investment in onboarding structure creates a compounding productivity tax that is invisible in any single hire but visible at the quarterly level when 8 engineers each require 14+ days to reach first contribution on a system that could have been made navigable in 7.

Property 2: The documentation freshness decay surface and the maintenance ownership gap. The documentation freshness decay surface is the rate at which onboarding documentation accumulates inaccuracies between new hire cohorts, determined by the structural gap between who is responsible for the system that a documentation section describes and who is responsible for the documentation section's accuracy when that system changes. The decay surface is not a function of how well the documentation was written — excellent documentation written at a specific point in time and not maintained decays at the same rate as adequate documentation — it is a function of whether documentation maintenance is a structural responsibility owned by specific people who receive triggers when the documented systems change, or an informal expectation that relies on authors of system changes to remember that documentation exists and to check whether their change requires an update. The decay surface has a characteristic distribution: environment setup documentation decays fastest (because it is sensitive to version numbers, tool paths, and configuration values that change with each infrastructure update), architecture overview documentation decays more slowly (because architectural decisions are stable over longer periods), and conceptual or rationale documentation decays slowest of all (because the reasoning behind design decisions is often still valid even when the implementation has changed). A team that wants to reduce the decay surface should invest first in connecting the fast-decaying sections to the systems they describe — a setup step that references a specific service should live as close as possible to the configuration for that service, so that when the service configuration changes, the setup step is visible to the engineer making the change. A team that cannot invest in structural co-location should invest in a quarterly freshness review process: the engineering manager or a designated senior engineer reviews each section of the onboarding documentation against the current state of the system it describes, flagging sections that have drifted and scheduling updates before the next hire cohort. Connect this property to the documentation strategy decision record: the onboarding documentation freshness problem is a specific instance of the general documentation maintenance problem, and the documentation strategy decision determines the structural model for all documentation maintenance in the team; a documentation strategy that specifies "documentation lives close to the code it describes, and the code reviewer is responsible for checking whether documentation requires an update" provides the same maintenance model for onboarding documentation as for system documentation; a documentation strategy that does not specify a maintenance model produces maintenance that is informal, inconsistent, and dependent on individual initiative, which produces documentation decay rates that track codebase change rates exactly.

Property 3: The onboarding quality variance surface and the buddy model design problem. The onboarding quality variance surface is the range of ramp experience quality across new engineers in the same cohort, produced by structural variation in the support they receive during the onboarding period — not by variation in their individual capabilities or prior experience. The variance surface is determined almost entirely by the buddy model design: a buddy model with a defined time budget, defined responsibilities, and a minimum check-in cadence produces low variance (because each new engineer receives approximately the same support regardless of which buddy is assigned); a buddy model with an informal availability expectation and no time budget produces high variance (because each new engineer's support quality depends on the buddy's personality, current sprint load, and personal philosophy about mentoring). The high-variance outcome is the structural default because it requires no design — informal buddy availability is the natural state of most engineering teams, and adding the label "buddy program" to informal availability does not change the variance. The low-variance outcome requires active design: the time budget must be specified before the buddy assignment (so the sprint planner can adjust the buddy's feature allocation), the responsibilities must be written down (so the buddy knows what the role requires before accepting it), and the check-in cadence must be explicit (so the new engineer knows when to expect contact and does not interpret silence as a signal that they should not ask for help). Teams that measure average ramp time will not see the variance surface — the average of 3 weeks and 14 weeks is 8.5 weeks, which is a mediocre but not alarming number that does not trigger a program redesign. Teams that measure the distribution and investigate the high ramp-time cases will discover that the high-ramp-time cases cluster around buddy unavailability and that the fix is structural rather than individual. Connect this property to the engineering hiring process decision record: the hiring process predicts the new hire's capability and experience level at entry; the onboarding program determines how much of that capability is productively deployed in the first 90 days; a team with a strong hiring process and a high-variance onboarding program is leaving a predictable fraction of its hiring ROI on the table every cohort, because the variance in onboarding quality is not correlated with the variance in hire quality and does not average out across cohorts.

The developer onboarding program ADR: five sections

Section 1: Ramp structure model. The ramp structure section should specify the explicit model for a new engineer's first 30 days — whether it is a milestone-driven path, a buddy-only model, a self-directed exploration model, or a combination — and the reasoning for the choice including the trade-offs that the choice accepts. A milestone-driven path (day 1: environment setup complete; day 3: first codebase exploration task; day 7: first draft PR open; day 14: first PR merged; day 21: first meaningful feature task assigned; day 30: retrospective) provides the lowest time-to-first-contribution floor and the lowest variance because the milestones create explicit checkpoints where a manager or buddy can identify whether the new engineer is on track and intervene if they are not; the cost is that someone must design the milestone path and maintain it as the codebase evolves. A buddy-only model (assign an experienced engineer and rely on them to guide the ramp) provides flexibility and scales naturally with team size but produces the high variance described in the second failure pattern above; it is the default model for most teams because it requires no upfront design. A self-directed model (provide documentation access and let the senior engineer find their own path) works for highly experienced engineers onboarding to a familiar technology stack and a well-documented codebase, and fails for everyone else; it is often the implicit model used by teams that have not made an explicit ramp structure decision. The section should specify which model the team uses, why it was chosen over alternatives (not just what was convenient but what trade-offs were accepted), and what the expected time-to-first-contribution range is under the chosen model. Connect this section to the engineering team growth decision record: the ramp structure model that is correct for a 10-person team hiring one engineer per quarter may not be correct for a 40-person team hiring 8 engineers per quarter; a milestone-driven path that requires a senior engineer to facilitate each new hire's codebase tour will consume 6 senior engineer-days per quarter at the first scale and 48 senior engineer-days per quarter at the second scale — a 48-day investment that requires either significant senior engineer allocation or a redesign of the codebase tour into a self-serve format that does not require facilitation; the ramp structure decision should be revisited when the team's hiring rate changes significantly enough that the time investment in onboarding begins competing with the time investment in feature delivery.

Section 2: Time-to-first-contribution target and measurement. The measurement section should specify the definition of "first contribution" used as the measurement target, the target number of days from start date to first qualifying PR merged, who is responsible for logging the data for each new hire, and how the data is reviewed. The definition of first contribution matters because different definitions produce very different numbers and different incentives: "first merged PR of any kind" incentivizes merging documentation typos in week 1, which produces a good metric and a new hire who has not yet demonstrated they can navigate the codebase independently; "first merged PR that addresses a meaningful piece of scoped work" — a bug fix in an existing feature, a small feature addition, a performance improvement with a measurable before and after — produces a metric that is harder to game and that reflects genuine productive ramp. The target should be a ceiling, not an average: if the current average is 35 days and the target is 21 days, the target communicates that anything above 21 days is a signal to investigate the ramp structure rather than a reflection of individual capability. The logging mechanism should be explicit — a spreadsheet, a table in the team's analytics system, a field in the applicant tracking system that is filled in when the first qualifying PR is merged — because a measurement that requires someone to remember to log it will not be logged consistently and will produce data that is missing for the hires who had the worst ramp experiences (the hires whose managers were too focused on helping them catch up to log the data). Connect this section to the engineering metrics decision record: the time-to-first-contribution measurement is an engineering metric, and the decisions that apply to all engineering metrics apply here — the metric should be specified before the first measurement is taken, the operational definition should be stable across cohorts (so that changes in the measured number reflect changes in the ramp structure rather than changes in the measurement definition), and the metric should be reviewed in a context where it can inform a decision rather than in a context where it is reported as a vanity number; a time-to-first-contribution metric that is measured but never reviewed against the ramp structure decisions that determine it is a metric that produces reporting effort but no learning.

Section 3: Onboarding documentation model. The documentation section specifies who writes the onboarding documentation, who owns its accuracy after it is written, the maintenance cadence, how new hires contribute updates as they follow the documentation, and how the team identifies sections that have drifted from the current system state. The authorship model should specify who writes each section: environment setup documentation is best written by the engineer most recently responsible for the environment configuration (because they have the most current understanding of it), while architecture overview and codebase tour documentation is best written by the most experienced engineers who have the broadest system understanding. The maintenance ownership model is the section most teams omit and the section whose omission produces the third failure pattern: each section of the onboarding documentation should have a named owner who is responsible for its accuracy and who is notified when a change is made to the system the section describes. The "update as you go" contribution model for new hires should be an explicit task in the onboarding checklist, not an informal expectation: every new engineer should be asked to update any step that did not work as written and to note the date of the update so that freshness can be assessed. The freshness review cadence should be explicit: a quarterly review of all onboarding documentation sections by the designated owners, with a checklist approach (mark each section as verified-current, needs-minor-update, or needs-major-rewrite) that produces a clear picture of documentation health before the next hire cohort starts. Connect this section to the documentation strategy decision record: the onboarding documentation model should be derived from the team's broader documentation strategy rather than designed in isolation; if the documentation strategy specifies that documentation lives close to the code it describes (a "docs as code" approach where setup documentation lives in the repository alongside the configuration it describes), the onboarding documentation model can leverage the same maintenance mechanism as other system documentation; if the documentation strategy specifies a wiki-based approach, the onboarding documentation should have explicit wiki page owners with defined review cadences, and the wiki should have a mechanism for flagging pages as potentially stale when the systems they describe are modified.

Section 4: Buddy program structure. The buddy program section specifies whether the team uses a buddy model (and if so, what the buddy's role is relative to the engineering manager's role in onboarding), the buddy's defined time budget per week, the minimum check-in cadence, the defined responsibilities, how buddy quality is assessed over time, and how buddy assignment accounts for the buddy's current sprint load. The time budget specification is the most important element because it is the only element that prevents the buddy assignment from being eaten by sprint commitments: a buddy who has been allocated 2 hours per week for buddy work in their sprint plan will protect those 2 hours; a buddy who has not received a time allocation will allocate 0 hours in weeks when the sprint is at full capacity and 2 hours in weeks when slack exists, producing the inconsistent availability that characterized the second failure pattern. The minimum check-in cadence should be explicit: a 30-minute daily sync for the first 5 business days (after which check-ins move to 3 per week for weeks 2 and 3, then weekly for week 4) creates a structured contact cadence that gives the new engineer predictable access to their buddy and prevents the "I didn't want to interrupt" dynamic that causes new engineers to spend 4 hours debugging a problem that the buddy could have solved in 10 minutes. The buddy assignment process should include a sprint load check: the engineering manager should review the proposed buddy's sprint commitments for the 4-week onboarding window before making the assignment, and should assign a different buddy if the proposed buddy is carrying a delivery commitment that is already at capacity. Connect this section to the code review policy decision record: the buddy's code review of the new engineer's first 3 to 5 PRs is the highest-leverage onboarding activity for establishing team conventions and preventing the new engineer from internalizing patterns that will require correction later; the code review policy should specify that first-PRs from new engineers receive buddy review as a required step before or alongside standard reviewer assignment, and the buddy's review should focus explicitly on 'this is how we do X here' — the team-specific conventions that are not visible from the codebase alone and that new engineers will get wrong systematically until they receive explicit correction; a code review policy that does not differentiate between reviews of new-engineer PRs and reviews of experienced-team-member PRs misses the highest-leverage use of code review as an onboarding mechanism.

Section 5: Feedback loop and iteration cadence. The feedback loop section specifies what data is collected from each new hire cohort, who reviews the data, what the trigger is for revising the onboarding program, and how revisions are made with a specific owner and deadline rather than deferred indefinitely. The data collection model should include a structured retrospective at week 4 and week 8 with questions focused on specific friction points (which steps were broken or unclear, which topics required the most back-and-forth with the buddy or other engineers, which information was missing that would have accelerated the ramp) rather than overall satisfaction scores (because overall satisfaction scores reflect personality and comparison to prior jobs as much as they reflect the actual quality of the onboarding program). The ramp time log should be joined with the retrospective data at the cohort level: engineers who ramped slowly should be investigated specifically for structural causes (buddy availability, documentation accuracy, access provisioning delays) rather than attributed to individual factors. The trigger for revision should be specific rather than open-ended: if any engineer in a cohort has a time-to-first-contribution above the target ceiling, a retrospective investigation of that ramp is required and any structural causes identified must be addressed before the next cohort starts. The revision owner should be specified by name, not by role, and the revision deadline should be tied to the next expected hire start date. Connect this section to the open-source extractor: the developer onboarding program decision — what structure governs the first 30 days, what the time-to-first-contribution target is, who owns documentation accuracy, how buddy responsibilities are defined — is made in conversations: an engineering manager and VP Engineering on a call after two consecutive bad onboarding experiences, a planning session where someone notes that the last three hires all took 12 weeks to ramp and that the runbook is probably out of date, a Slack thread where a new hire reports that the Docker setup instructions don't work and the senior engineer replies with the correct configuration rather than updating the documentation; the written output of these conversations is the onboarding runbook and the buddy assignment in the new hire's calendar invite; the reasoning behind the ramp structure choice, the documentation maintenance model that was never established, and the buddy time budget that was never specified live in the chat history that preceded the runbook's creation and decayed invisibly in the absence of a structural maintenance model — exactly the context that WhyChose's extractor recovers from AI chat export history and makes searchable before the next bad cohort experience repeats the question.

FAQ

Further reading

• Engineering hiring process decision record — the hiring process and the onboarding program are sequential decisions whose consequences are entangled; a hiring process that selects strongly for directly relevant senior experience can tolerate less onboarding structure, but only if that assumption is made explicitly and tested against actual ramp time data; the assumption that senior engineers will self-direct successfully regardless of onboarding quality is a bet on hiring accuracy that becomes expensive the first time a strong hire exits because the environment setup documentation was stale and the buddy was at sprint capacity.
• Documentation strategy decision record — the onboarding documentation freshness decay surface is a specific instance of the general documentation maintenance problem; the documentation strategy determines the structural model for all documentation in the team, and the maintenance mechanisms that apply to system documentation (ownership, co-location with code, update triggers when the described system changes) are the same mechanisms that prevent onboarding documentation from decaying between hire cohorts; a documentation strategy that does not specify a maintenance model produces onboarding documentation with a predictable 18-month half-life.
• Developer experience decision record — the onboarding program is the highest-leverage point in the developer experience investment timeline, because the new engineer's perception of the team's code quality, tooling, and collaborative norms is being formed in a narrow window where first impressions have outsized weight; a developer experience investment that produces excellent tooling for tenured engineers but a broken local environment for new engineers will not appear in the developer experience metrics collected from tenured engineers, and will appear in the ramp time data only if ramp time is being measured.
• Engineering team growth decision record — the time-to-first-contribution floor is a compounding cost as the team scales; the structural minimum ramp time that is acceptable at a 10-person scale hiring one engineer per quarter becomes a significant productivity tax at a 40-person scale hiring eight engineers per quarter; the onboarding program investment required to reduce the floor from 14 days to 7 days is constant but the return compounds with each hire cohort, which is why teams that make the onboarding investment early see the highest return and teams that defer the investment until the cost is visible are operating at a compounding disadvantage for the entire period of deferral.
• Open-source extractor — the developer onboarding program decisions — ramp structure model, documentation ownership model, buddy time budget, first-contribution target — are made in conversations: an engineering manager and a VP Engineering on a Zoom call after a bad onboarding cohort, a Slack thread where a new hire reports that the runbook instructions are broken, a planning session where someone proposes building a better onboarding program and someone else asks who will own maintaining it; the written output is the runbook file in Notion and the buddy assignment in the calendar invite; the reasoning behind the ramp structure choice and the maintenance model that was never specified live in the chat history that preceded the runbook's creation — context that WhyChose's extractor recovers from AI chat export history and makes searchable before the next cohort discovers that 40% of the setup instructions no longer work.