Developer Onboarding Best Practices: How to Achieve a Day 1 Commit

At my first programming job, I sat down in front of a Windows NT server with ColdFusion and SQL Server and started banging out code within an hour of stepping through the door. The only distraction was a Weimaraner puppy who would occasionally wander in from another office to pee in the corner. I got a lot of work done at that job.

My second job was at the shiny headquarters of a well known corporation. They didn’t have a computer for me on day one, so I read docs and went to meetings. After several weeks my computer arrived. It took two days to successfully install Visual Age for Java and WebSphere from CD-ROM. Several days later I got access to CVS... All told, it was around six weeks before I could do a lick of work. I left that job after sixteen months. It was impossible to get anything done.

Give me my fix

Managers, I’m about to let you in on a secret. Normal people don’t become programmers. Programmers are basically junkies. Coding is their fix. 

Normies cannot understand how addictive it is to see your code light up in production. Nor can normies understand how excruciating it is when you can’t get your fix. This is why so many programmers have side projects. They can’t get their fix at work, so they get it wherever they can.

Therein lies the problem with the S.P.A.C.E. framework. S.P.A.C.E. assumes that programmers are normal people who respond to normal incentives. That’s wrong. If normal incentives worked on programmers they wouldn’t have become programmers. 

Engineering productivity doesn’t have to be complicated. If you give the junkies their fix, the rest pretty much takes care of itself.

Get them hooked

If you want to get your programmers hooked, you need a great onboarding program. What “great” looks like will vary from company to company, but the one thing I insist on is that new team members should be able to commit code and light it up in production on their first day. 

Why is this important? Obviously, a Day 1 Commit demonstrates your priorities as a delivery organization. But there is something more subtle. The Day 1 Commit demonstrates your fitness to lead. If you cannot figure out how to get to a Day 1 Commit, you are tacitly admitting that:

1. you don’t know how to run a production line

2. you don’t understand what motivates programmers

3. you don’t value your team’s time

4. you don’t value your employer’s money.

It’s a bad look.

How do you know if you have a problem?

When I started at my current gig, I noticed that it was taking two or three weeks for new team members to make their first commit. Maybe “noticed” isn’t the right word. The process was actually a little more deliberate. 

Within my first month, I introduced a software development analytics tool called Swarmia, which is essentially a less bloated version of Code Climate. Swarmia displays commit history and other analytics by mining GitHub data.

At the time we were hiring very aggressively and onboarding new developers every week. I spent a month or two poring over Swarmia data and zooming in on our new hires. 

The data supported my observation that it was taking too long for new hires to make their first commit. But how to fix it? That was the question. 

Over the months we tried a bunch of different angles to compress onboarding time. Here is a brief retrospective summary of the main levers we went after:

Sherpa

If you’re climbing Mount Everest, your sherpa is a native guide who shows you the way. Without the sherpa you might make it to the top…or you might end up dead. In software teams, an onboarding sherpa is usually a senior team member who has good understanding of the environment and tooling. The job of an onboarding sherpa is to guide the newbie through the onboarding process as quickly and painlessly as possible. 

Our sherpa program was somewhat successful, but since our department was brand new, we were all breaking new trail every day. Sherpas are supposed to guide newbies down the well-worn path. If there is no path, then everybody is a newbie together and there is a practical limit to how much a sherpa can help.

Onboarding documentation

I recommend an “everything-as-code” approach to documentation. All your onboarding docs should be expressed as markdown and stored in GitHub. Use a site generator like Docusaurus or Makedocs to deploy the docs within an internal developer portal. 

There are two main benefits to this approach. First, documentation goes through the same pull request review as production code. Peer review means our Docusaurus site is much more timely and accurate than Confluence. Second, new developers are both empowered and expected to own the correctness of our onboarding documentation. If they find a problem in our onboarding docs, they just edit the markdown, submit a pull request and get a gold star for doing the right thing.

Cloud developer environments

Cloud Developer Environments (CDE’s) are pretty cool, especially if you have a very complicated development environment that is difficult to replicate on fleet hardware. Things like Python virtual environments, NVM, or SDKMan can help abstract the underlying operating system, but they add complexity, which is the opposite of what you want if your goal is to compress time-to-productivity.

This is where CDE’s fit in. CDE’s like Codespaces or GitPod burn out your developer environment into a Docker image that runs in the cloud. With CDE’s it doesn’t matter if you’re laptop is Intel or Silicon, Windows or Mac, Sierra or Big Sur… The CDE guarantees a uniform developer environment, which makes onboarding a breeze. The last place I worked, we used Codespaces to get new devs coding in < 1 hour.

Unfortunately, most CDE’s require ingress from the cloud to your corporate LAN. If your network security policies forbid ingress, most CDE’s are off the table. We pushed on Codespace for a while, but alas, we have not yet been able to leverage CDE’s to improve onboarding.

Birthright entitlements

You can make a big improvement to your onboarding process through birthright entitlements. Birthright entitlements streamline the onboarding process by establishing foundational access permissions tailored to each role, eliminating the need for multiple access requests and approvals for new hires.

A typical birthright entitlement could collapse more than a dozen separate Service Now access requests into a single request that is completed before a new developer joins the team. Birthright entitlement can eliminate days and days of waiting waste, and has probably saved hundreds of thousands of dollars in billable hours.

The object lesson here is that institutional waste likely produces more drag on your onboarding process than your tech. 🤷🏼️

Recommendations

If you are looking to improve your onboarding experience, I have two recommendations.

First, I recommend that you assign a product owner or lead engineer to own and drive the process. Onboarding is one area where you want a very high degree of uniformity. Federating responsibility for your onboarding process invites variation and leads to chaos.

Second, to prevent drift, you are going to need continuous adjustments to your onboarding process. If you can’t institute a Day 1 Commit program, you should at least periodically monitor time-to-first-commit to make sure things aren’t getting out of hand.