Nobody Documented This Codebase. Your New Hire Noticed.
YOUR NEW HIRE NOTICED
Your new engineer is weeks in and still lost, because the map of the system lives in three heads. How to onboard people into an undocumented codebase.
TL;DR: You hired someone good, and six weeks in they're moving like someone exploring a cave with a lighter. That's not a hiring mistake - it's what onboarding into an undocumented codebase looks like, and everyone on your team is paying the same search tax daily; the new hire is just the only one who can't hide it. The fixes are routing and capture. And the map you think doesn't exist has actually been writing itself in git the whole time.
You did the hard part. You ran a real hiring process, paid a real salary, landed an engineer with a track record. Six weeks later they're asking questions in a tone that sounds like apologizing, their first PR took three reviewers and a week, and a small voice in your head has started asking whether you hired wrong.
Look at what you actually gave them on day one: a repo, a README with setup steps from two stacks ago, and a Slack channel where the real documentation lives: in the heads of three people they're afraid to keep interrupting. They're not lost because they're slow. They're lost because there is no map, and they're the only person in the building who's never seen the territory.
Why nobody documented the codebase (and why it isn't laziness)
Documentation loses a fair fight every single sprint. The people capable of writing it are precisely the people who don't need it, so for them it's pure cost, ranked against a deadline that pages someone. The knowledge stays tribal, the gap compounds, and the docs that do exist rot at the speed the code changes until they're worse than nothing: a map that confidently shows roads that no longer exist.
Nobody chose this. It's the same routing gravity that concentrates knowledge on single owners: capture always loses to delivery unless the system deliberately protects it. Which means "everyone please document more" isn't a fix; it's a wish.
What an undocumented codebase costs every single day
The new hire pays the most visible tax, but check the ambient rate: in the 2024 Stack Overflow survey, 61% of developers said they spend more than 30 minutes a day searching for answers or solutions. That's your whole team, every day, doing archaeology. The newcomer is simply excavating with no reference layer at all.
It compounds. Slow ramp means months until a hire ships meaningfully, and remote makes it harder still: Rodeghero et al.'s study of 267 new hires onboarding onto Microsoft teams found that building social connection was a central struggle, and an undocumented codebase makes every question a social transaction. And the endgame of knowledge that never gets captured is an area only one person can touch. Today's onboarding friction is tomorrow's bus-factor finding.
How to onboard into an undocumented codebase
Free, and none of it is a documentation sprint:
- Assign a navigator, not a buddy. One named person whose job for four weeks is the new hire's unblocking, with time carved out for it. "Ask anyone anything" reads as welcoming and functions as "interrupt someone important, repeatedly."
- Choose first tickets by redundancy need, not by easiness. Route the newcomer into areas where the team most needs a second pair of hands - building coverage where one person carries everything - with the current owner navigating.
- Make the missing doc the first deliverable. The newcomer writes the onboarding guide they wish they'd received, as they learn. Newcomer confusion is the best documentation generator you have: they see every gap the experts have gone blind to, and the writing forces real understanding.
- Use review as the teaching channel, deliberately. Bacchelli & Bird found code review's actual outcomes lean toward knowledge transfer and team awareness; put the newcomer on review rotations in their target areas and treat explanatory review comments as documentation being written in the only place it stays current.
- Record the "why" from now on. You can't backfill five years of design rationale, but every decision from this week forward can cost one paragraph while it's fresh. Continuous capture is the only version of documentation that survives contact with the transfer problem.
The map that exists even when the docs don't
One reframe changes the onboarding conversation: your codebase is not actually undocumented. One record has been maintained with perfect discipline since commit one, and that's the git history. Who really works on each area. Which files change together. Where knowledge concentrates, and which areas are one person deep.
Busfactor turns that record into the map your new hire never got: ownership per area, authorship-weighted and review-aware, with the risk zones flagged, so you can route onboarding into the areas that need redundancy most and know exactly who should be navigating. The honest limit: git shows who and where, never why. Design rationale lives only in heads until someone writes it down. No tool can excavate a decision that was never recorded, ours included. The map doesn't replace steps 3 and 5; it tells you where they'll pay off most.
The door
Your new hire isn't the problem - they're the most accurate sensor you have, reporting faithfully on a gap an acquirer's analyst would also find, and that ninety minutes of tabletop drilling would confirm. This week: name the navigator, reroute the first tickets, commission the doc-they-wished- existed. And if you want the map before the next hire starts, connect your repos and give day one a territory with roads on it.
Frequently asked
How do you onboard engineers into an undocumented codebase?
Route them, don't drop them: assign a navigator who owns their unblocking, pick first tickets in areas where the team needs redundancy, and make 'write the doc you wish existed' part of the first deliverables. Review is your best teaching channel: the research on code review consistently finds knowledge transfer is one of its main real outcomes.
Why do codebases end up undocumented?
Because documentation loses a fair fight every sprint: the people able to write it are exactly the people who don't need it, deadlines outrank prose, and docs rot at the speed the code changes. It's an incentive problem, not a character problem, which is why 'everyone please document more' has never once worked.
Should we stop feature work and run a documentation sprint?
Usually no. Big-bang documentation sprints produce shelf-ware written by the wrong people at the wrong altitude, and it starts rotting immediately. Continuous capture beats catch-up: docs written by newcomers as they learn, decisions recorded when they're made, and review rotation spreading the knowledge that never makes it to prose.
Can you understand a codebase without documentation?
Partly. The repository itself is a record nobody can forget to update. Git history shows who really works on each area, which files change together, and where knowledge concentrates. What it can't show is why decisions were made; design rationale still has to be written down by humans while they remember it.