Elijah Verdoorn

Programmer, Designer, Musician

Thoughts on Best Practices for Technical Onboarding


Like many tech companies, my team at Pandora experiences its fair share of employee turnover. Between personal experience and talking to others in the industry I know that this can be challenging for even the most well-organized teams since the loss of a long-tenured colleague means the departure of domain knowledge, codebase lore, and may take a bite out of team morale. I don’t claim to know how to fix all the problems caused by the loss of a valuable team member, but the work must go on and I do know that their position is often quickly filled by a new individual who is eager to get started. While a new person may never replace your grizzled veteran, you can take steps to help get them up to speed quickly. In an effort to help increase early productivity within my workplace I’ve been working on optimizing my team’s onboarding process to be as efficient as possible. Over the past eight months of leading the advancement and maintenance of these documents, I’ve made a few observations that may be helpful for others who are looking to improve their equivalent processes.

Onboarding lives at the intersection of recruiting, human resources, and technical work streams, optimized practices in this area will require cooperation across all these departments. Given my job title I focus on the technical side of this equation; I would encourage technical readers to meet with other involved parties to align on a system that meets everyone’s needs. A perfect system from one department’s perspective might be a disaster for another, it is better to have cohesion than perfection of any one area. While my day-to-day work may be with the Android platform, I believe that a good portion of what I’ve discovered can be applied to many different engineering teams, and the principles outlined below can be extended well beyond engineering teams.

I struggled to fully organize my thoughts on this topic into a cohesive narrative, so I’ve opted for a simple list of learnings in no particular order:

  1. A sense of progression is important. As alluded to, new employees are frequently highly motivated and want to feel as thought they are making a difference on day one. This is deeply ingrained in the industry, some engineering positions even advertise this in their job descriptions: “put code into production from day one”. I’m not convinced that getting every new employee shipping code on day one is all that important, but at least make sure that they’re able to check off a few tasks before they pack up on their first day. A critical part of this progression is that the onboarding needs to have an “end”, a goal to work towards. I fully believe in the ideas of never stopping learning and growing in your role, but there should be a point where new team members can feel as though they’ve completed their initial tasks and are “full members” of the team; this usually aligns with the completion of the onboarding. Reaching this point bestows a sense of individual empowerment, where your new teammate can feel like they have enough foundational information to fully contribute to team decisions and codeline.

  2. No throwaway work. Nothing feels worse than doing work and having it be tossed to the side, there is no reason that you should have the energy that new hires bring to a team go to waste on projects that will quickly discarded after they have been deemed to be “ready for real tasks”. I’m not suggesting throwing your new hires off the deep end into the toughest bugs your team faces, but make sure that whatever they’re doing in their first few days has demonstrable value and will endure beyond the context of their training. If you are in a position anything like my team, you’ve got plenty of easy “nice to have” bugs or features that you can hand off with relative ease to a newcomer!

  3. Your onboarding process should be both a quick start guide and an index to the owners manual at the same time. To accomplish this is an exercise in balancing technical depth with relevancy and timeliness. Providing short summaries and linking to locations where new hires can go to get more depth on any given topic is a good way to keep the length down while ensuring that the information is available when needed. Every piece of information that you provide should have a purpose, you should strive for “just in time”: Keeping the system-expected version of your build system in-line next to the download link? Very technical, but also very timely and important. A table of corporate-preferred travel partners? Less technical, but also less relevant - probably would be better to separate that information and link to it.

  4. Consider embracing optional tasks. Everyone works differently and prefers different setups. The goal of a set of onboarding instructions should not be to change anyone’s mind about what is the best way to do work, but to present the resources that exist on a team for following in the footsteps of successful past employees. One way to disseminate the information about existing resources without forcing anyone to change their workflow is to simply mark a task as optional. New hires get the opportunity to see what resources area available to them, but won’t feel pressured to significantly change their toolchains if they feel effective and comfortable with their existing systems. I’ve found that this applies especially to heavily personal-preference system like terminal configurations, git clients, and (perhaps most of all) text editors.

  5. Designate a single person for each new hire that will be available to answer questions that come up during the first few days. At Pandora we assign mentors that take new hires through the onboarding process, including having a one-on-one meeting at various points in the process to ensure that the new hire has an opportunity to ask in-person questions and are adjusting well to their new role. This person doesn’t need to have all the answers, nor make the new hire their primary focus, but they should be approachable about anything ranging from the logistical (“Where do I get a cable to connect my monitor to my laptop?”) to the technical (“Can you point me in the direction of the code that manages user authentication?”) for the first weeks of a new employee’s tenure.

  6. Be data-driven. We all try to drive our product decisions based on data, why not do the same with our internal processes? Laszlo Bock (former Senior Vice President of People Operations at Google) wrote in his book “Work Rules!” about how Google measures and optimizes almost every aspect of the work lives of Googlers; inspired by this approach I started gathering data on our onboarding: what step took the longest? What was the step that sparked the most questions? How long did the entire process take, and how much does that time vary with the experience level of the hire? All that information was good for tweaking wording, breaking up big tasks into manageable chunks, and knowing where to add more instructions to clarify confusion. A clear win, but it failed to capture a key metric - How did people who went through the process feel? I resolved this by adding a simple survey as the final required task in the process, and from that have been able to see a different perspective on how my changes are affecting the ramp-up experience. In this survey I ask how completing the onboarding made the new employee feel, what they struggled with, and what worked well for them. I periodically compare this with the empirical data that I gather and use this to determine where I ought to spend time improving the onboarding.

  7. Keep the documents up to date. While this may seem obvious, it is so critical that I feel as though it warrants mention here. These documents represent some of the first impressions that new employees will have of what the documentation and communication standard is in your workplace. Make keeping these documents up to date a team effort, assign a point person to manage them, develop a regular review cycle around them, whatever it takes for them to stay current. It isn’t enough to scramble right before meeting your new colleague to make changes that should have been made over a period of weeks or months.

What does all that look like in practice? At Pandora, we track our tasks in Jira, and have a central project set up for all engineering onboarding. Each team maintains an epic in this project, creating and editing tasks for new hires under their epics. When a team needs to onboard a new member, they clone the relevant epics and assign them (and their sub-tasks) to the new hire. The new hire then sets about completing all the tasks in their epic, operating at a self-directed pace. This roughly mimics the day-to-day work of an individual contributor, so simply by following this process the new developer is gaining experience in the company workflow. I have found this practical approach is especially important for new grad hires, who may not have been exposed to corporate task-tracking software or the mechanics of completing an individual unit of work. Jira also makes this process transparent to all interested parties, where the new hire knows how many tasks are remaining, a manager or mentor can check in on the new hire and ensure that they are making progress, and there is a record of what information the new hire has received (can be important for company-wide training mandates like security, workplace conduct, and legal processes). The Android team’s task list takes somewhere between three days and a full workweek to complete, a length that management and developers have reported being happy with. Data coming in from the closing survey is overwhelmingly positive, developers hired into all levels report that they feel prepared to take on feature work after completing their initial tasks.

I’m immensely pleased with the results (both anecdotal and numerical) I’ve seen so far, but I still have a variety of ideas for improvements that I want to make, and theories that I want to test. My most prominent thought is to keep asking “Can more be done to break the information up into digestible pieces?”. While I don’t think that the overall length of the process can be significantly shortened, I want to explore modularizing the tasks into subsets and presenting them to new employees just before they dive into relevant work. My vision of an implementation of this would start the typical first day information, just enough to get started fixing bugs. Then the hire could take a week or two and focus on getting familiar with the codebase and adjusting to their new job. Once they get started on their first feature work, they could be assigned a second set of tasks to familiarize them with the feature development workflow and tooling. The current “master” epic containing all our tasks could then be broken up into numerous such modules for different tasks: release management, product design, and test automation, just to name a few. Education principles remind us that information retention from showing and telling fall behind the amount of information retained when learners engage with the process; splitting up the onboarding process would allow for more doing and less telling.

What are the processes that you have in place for onboarding? Are there other potential areas of improvement that I haven’t thought of? I’d love to start a conversation around industry practices in this area and discover together how we can be most welcoming to new teammates, feel free to reach out with your thoughts - my contact information can be found on this site.