The Struggle Is Real

This week I got into a friendly debate about developer onboarding in two different fora (the Rands Leadership Slack and an in-person CTO Lunches gathering). My hot take: technical onboarding documentation is at best over-rated, at worst counterproductive, and most organizations shouldn’t give it much thought.

Before you pick up stones, hear me out. My logic is based partly on experience, and partly on a theory. The experience is that writing detailed onboarding steps takes considerable time, usually from well-tenured developers whose attention is better spent elsewhere. Keeping said documentation up-to-date takes even more time and is nearly impossible to do with a fast moving product. And having half-baked or incorrect instructions is worse than nothing for a new team member. Putting in all this effort just to save a little bit of onboarding time doesn’t make sense. The juice isn’t worth the squeeze.

But there’s more. My theory is that having an onboarding process spelled out in painstaking details actually robs the newcomer of the chance to build muscle through struggle, shortcuts creative exploration of how things could be better, and sets an expectation that “getting up to speed” means following a mechanized set of steps instead of self-directed discovery of a codebase and getting to know fellow team-members and their institutional knowledge through asking excellent questions.

Sure, this might mean some initial frustration. That can be managed. And it might mean a new developer is slower to begin delivering value. But my hypothesis is that once they do, they’ll be better prepared to provide broader and deeper value in the long run.

And besides, it’s likely your system isn’t as complex as you think it is, and you should be looking for the kind of people that can do their own problem-solving. If it takes someone many days just to get an app running, you’ve got more serious problems. Which makes me think this could make for an interesting interview exercise: “Here’s our code repository. Get it running in a fresh environment.”