A new engineer costs $15K/month while they ramp. Docs cut that in half.

A new engineer costs their full salary from day one while producing near-zero output during their ramp period. At a US senior engineering salary of $180,000-$220,000, the monthly loaded cost is roughly $15,000-$18,000. During the weeks when that engineer is reading code, asking questions, attending walkthroughs, and generally absorbing context rather than shipping, the company is paying full price for a fraction of the output.

This is entirely normal and expected. The question isn't whether there's a ramp period but how long it lasts, and the single biggest lever on ramp duration is the quality of the documentation the new hire has access to.

The documentation difference

In a team with comprehensive, current documentation, a new engineer's first week looks like this: read the architecture overview, understand the key systems and how they interact, review the decision log for major technical choices, follow the setup guide, deploy a small change. They have questions, but many of them are answered by the docs, and the questions that remain are specific and targeted rather than broad and contextual.

In a team without documentation, the same engineer's first week looks different: find someone willing to walk them through the system, absorb what they can from a verbal overview that's necessarily incomplete, stumble through a setup process that's partially documented and partially based on asking around, and spend considerable time trying to understand not just the system but who to ask about which parts of it.

The difference in ramp time is typically four to six weeks for well-documented teams versus eight to twelve weeks for poorly documented ones. At $15,000-$18,000 per month, cutting the ramp from ten weeks to four weeks saves $22,500-$27,000 per hire.

At ten engineering hires per year, which is typical for a growing startup, that's $225,000-$270,000 in recovered productivity. For larger organisations hiring twenty or more engineers annually, the savings scale proportionally.

What good onboarding docs contain

Not all documentation helps with onboarding equally. The highest-leverage onboarding docs are:

System architecture overview. A map of the major services, how they communicate, and what each one is responsible for. This gives the new hire a mental model of the whole system before they dive into any single component.

Getting started guide. Step-by-step instructions for setting up the development environment, building the project, running tests, and deploying a change. Every minute the setup guide saves is a minute the new hire doesn't spend asking someone else for help.

Key decisions and their reasoning. The decision records that explain why the system is built the way it is. Without these, the new hire will either make mistakes that repeat resolved problems or spend time relitigating decisions that have already been made.

Team conventions. Coding standards, PR review expectations, deployment procedures, incident response protocols. The unwritten rules that experienced team members follow unconsciously and new hires learn by trial and error when they're not documented.

Who does what. A map of team responsibilities, system ownership, and who to ask about specific areas. This alone saves hours of the new hire's time that would otherwise be spent figuring out the team structure through trial and error.

Self-writing onboarding docs

The irony of onboarding documentation is that it's typically created reactively, in the weeks before or after a new hire joins, by the senior engineers who are already the most stretched. The documentation is created under time pressure, and because it's created for a specific hire, it often isn't maintained after that hire no longer needs it.

Self-writing documentation changes the economics by generating onboarding materials continuously from the team's ongoing activity. Architecture documentation stays current because it's generated from PRs and design discussions. Decision records are captured as decisions are made. Convention documentation reflects actual practice rather than aspirational guidelines.

When the next hire joins, the onboarding materials already exist and are already current. No sprint of documentation work, no pulling senior engineers away from their own projects, no rushed wiki pages that'll be outdated by the next quarter.

Frequently asked questions

How do we measure the ROI of better onboarding docs? Track time to first meaningful PR (or first production deployment) for new hires before and after improving documentation. This is the most direct measure of ramp time. Also track the number of questions new hires ask in their first month, which tends to drop significantly when good docs are available.

What's the most important onboarding doc to create first? The system architecture overview and the getting-started guide. Together, these address the new hire's most immediate needs: understanding what the system does and getting it running locally.

Does this apply to contractors and freelancers? Even more so, because contractors typically have shorter engagements and less tolerance for long ramp periods. Good documentation lets a contractor become productive in days rather than weeks, which means the organisation gets more value from the engagement.

Related reading: The bus factor, The hidden cost of tribal knowledge, Documentation debt. Related pages: Self-writing docs, Onboarding, For engineering teams.