I imagine that most engineers have endured at least one painful onboarding experience. Every person I’ve asked has given me a unique example, from relying on piles of outdated notes to being stuck in some sort of task-less limbo and forgotten by the rest of the team. What should be your first impression of a new team can turn into a nightmare if that process isn’t handled properly.
In this post, I will describe some common themes from these bad experiences, as well as how a team can identify them proactively and work towards a better experience for their next new engineer.
A team’s documentation is precious. When we take the time to write out an explanation or a set of instructions, we expect that someone will eventually come along who needs this knowledge. What better candidate than an engineer who is brand new to the team, right?
While this may be true, keep in mind that a new engineer is going to have a lot of things on their plate. Rather than bombarding them with everything at once, it might be worth examining your docs and grouping the information into two main categories:
- Things they need to know right away
- Things they need to know eventually
All of the information may be important (why would it be in your docs otherwise?), but it is crucial to make the distinction between items that a new hire will need on their first day versus something that they may not need until a few weeks later. As a general example, knowing how to checkout and run your team’s code is probably a higher priority than learning all of the nuances of your user workflows.
Once you’ve narrowed down the parts of your documentation that are important for new engineer onboarding, you can start aggregating them into something like an Onboarding Checklist. Decisions of how to organize it, where to store it, and whether to reference existing doc pages or just rewrite the relevant parts from scratch are all things you can refine over time. Just remember that your goal is to make it as easy as possible for the reader to follow without getting lost along the way.
For Onboarding Documentation, the Medium Matters
Considering documentation, another key point bears mentioning: pay attention to what format the information lives in. Each medium (video, markdown page, spreadsheet, etc.) will have its own strengths and weaknesses, and these need to be considered when deciding what things to include during onboarding.
Recording a product demo might be a great way to show how your application works, but nobody wants to rely on that as their sole source for small snippets of information. Conversely, a complicated series of testing screenshots could be way too verbose for something that a new hire could learn from a 2-minute video.
Try to envision yourself being given these things as your only source of information. If the pieces you care about are difficult to extract, it may be worth creating an onboarding-friendly version to reference instead.
Nothing activates my Imposter Syndrome like being unable to help a team, something which is largely unavoidable during new engineer onboarding. The longer it takes for a new hire to configure their machine, the longer they’ll be unable to contribute. If this phase in your process requires too much manual effort, adding automation might help.
Modern tooling gives us plenty of options to consider. If your codebase requires a complicated or fragile setup in order to begin development, could this be packaged into a dev container where those actions can be offloaded to Docker? If your setup is even more-involved and can’t be recreated within a container, are there aspects that could be scripted rather than done manually? What about moving some resources to a shared environment in the cloud?
To be clear, the ideas above will not be appropriate for every team. Dev containers, shared environments, and other techniques for setup automation can all have drawbacks, and their added complexity might not be worth it for simpler stacks.
As a general test, imagine how long it would take to be productive if you migrated to a new machine. Reinstalling some tools for a couple hours may not be a big concern, but if you’re in for a long gauntlet of version-checking and custom directory structures, consider packaging that effort into something reusable.
Where to Ask for Help
This point may seem too obvious to be worth mentioning, but it’s easy to overlook. When you bring a new engineer onto your team, make sure that they have a specific person or place they can go to for help.
Whether this is a chat channel, a designated mentor, or even an email address, the keyword here is “specific”. Phrases like, “anyone can help you if you get stuck,” can be paralyzing when you haven’t memorized all of the roles or names across the team, and the last thing you want is for someone to resist asking for help when they need it.
Define the Finish Line
Another point that seems simple is how your new engineer will know when they are done, yet this can be difficult to pin down. The engineer onboarding phase is interesting in that it has a definite beginning, but it rarely has a defined ending. Someone who has just finished onboarding probably still has a lot of information to learn over time, a fact that can blur the distinction further. For that reason, let’s do what we can to establish a goal.
What goal should you set? If your team works toward the Onboarding Checklist idea mentioned earlier in this post, a natural candidate for the finish line could be the end of that list. Maybe your team wants to take it a step further and assign some newbie-friendly code change as the target. Or maybe there’s some other option that suits your environment even better.
Our intention here is to give your new engineer a metric they can use to measure their progress. Telling someone to reach out once they reach the end of a list is much more straightforward than simply asking them when they’ll be ready for a new task. Whatever goal you set, having this extra structure to your process can make it easier for someone to estimate how much work is remaining.
Evaluate the Results
Lastly, and maybe most importantly, is the idea of capturing feedback. The best opportunity to judge the effectiveness of your onboarding process is right after someone has gone through it.
If your documentation is difficult to follow, your new hire will know. If your development environments are hard to set up, theirs may not be configured correctly. Try to give them a safe environment to explain what worked well for them and what didn’t, and pay attention to the points they bring up. These areas could need some refinements over time.
Maintaining Your Process
This leads us to the tricky part of this point: maintenance. If onboarding is a pain point for your team, refining that process is very important. However, since your team and codebase will probably evolve as time goes on, this is likely not a one-time task. Similar to code, our processes and documentation tend to rot when neglected for too long, so do what you can to treat them with adequate respect.
As stated earlier, onboarding is your team’s first impression on your new engineer. We want them to have a pleasant experience, to feel welcomed, and be unhindered as much as possible. A team might need to invest some work before they have an onboarding process that they’re proud of, but that work pays dividends each time the team adds someone new.
And hopefully, when someone asks them about their best onboarding experience, your team comes to mind.
Do you have an onboarding experience you’d like to share? Drop it in the comments below, and be sure to subscribe to the Keyhole Dev Blog for more.