On-boarding Engineers

Being the new engineer on a team can be stressful and confusing even at well-run companies. You’re often hit with a flurry of information from a million different sources. Furthermore, we all hate being put into the most awkward of situations; having what you think is a dumb question. Should I ask in slack? I don’t want to distract everyone. Surely this is documented on the wiki… but the search function stinks. Do they expect me to figure this out myself?

The challenge with on-boarding is getting the right information to the right people at the right pace. Managing this from the top down is effectively impossible. Everyone works at their own pace so a one-size-fits-all approach will be either too slow or too fast for most. Not to mention your organization might be changing quickly so the material itself would need to be updated frequently.

I have run into this problem at big companies and small and have found a handy solution.

Meet the Technical On-boarding Guide

Think of all the things that your team might have to do on a daily basis;

• checkout and build code, trigger tests, run basic infrastructure in the cloud
• collect, review and address comments on design documents
• lookup internal documents for reference
• ask particular questions in an awkwardly named chat channel

It is generally a good idea to collect all of this information in a single spot. The problem is how to get people to read and understand it. In my experience it is simply too overwhelming for most new hires to be handed a giant document explaining how to do all of these things.

As engineers we like to solve problems. So give us problems.

The Technical Onboarding Guide is a collection of problems that new hires on your team work through in order to learn your company and your team’s internal tooling, methods, culture, and best practices.

The guide is not a test of your new hire’s chops, the interview is over and nobody needs that added anxiety. You’re going to employ the Socratic Method to ease new hires in to place by encouraging questions and walking them through the tricky parts of working at your company. So, it should be filled with slam dunks that guide them through your company’s spotty documentation, encourages them to follow the best practices you’ve been developing, and break down communication barriers by specifically encouraging them to post and ask questions in the appropriate places.

An Example Guide

Welcome new engineer to Fhqwhgads Inc! We’re excited to have you join the team. To help ease your integration with the team we encourage you to work through these common problems. If you have any questions we encourage you to first check our team’s wiki or wiki alternative, but always feel free to drop us a comment on our team’s common place for asking and Q&A.

1. Checkout and build the code base. How many tests are in our CI pipeline, what are the different stages? How’s our test coverage, do you think it needs improving? Where?
2. Read over this specific package which we feel exemplifies our coding standards quite nicely. It also solves this one common thing well and we tend to do that a lot in our code. How would you do blah with this code?
3. Try to visualize the solution to this common company specific problem. Here’s some unique tool we built to solve this. So and so most commonly maintains it.
4. Access this database that we use for storing logs. Use that database to figure out how many times we failed at blah last month.
5. Check out our dashboard tool, can you use it to tell when this service went down last? Can you issue a query and analyze how stable this other service is? Can you tell why it has to go down at this frequency?
6. Check in with the operations team via this common communication practice and ask them to help you do this common thing that we work with them to do. Schedule a time to meet with this other person. Don’t be shy, they’re expecting you!
7. Checkout this page that we use to share out design docs, page through them! Feel free to check out this one in particular since its a big project we’re currently working on. We commonly create design docs for projects that last more than a month.
8. Insert a few relevant technical challenges that require people to do things like;
   * submit code and ask their onboarding buddy or teammates for a review (encouraging them to follow your style guide)
   * create tests that leverage your build/test infrastructure
   * analyze results to an old but still relevant problem, making use of your data science tools

A couple of notes

Don’t be afraid to go into detail on these problems and to ask for particulars.

I have found that writing a guide that takes about a week to work through is generally appropriate.

It can be hard to find the right tone, be friendly but avoid being patronizing.

#8 above is going to be the most important one and you should be able to come up with several examples. Again keep in mind this should take a new hire about a week to complete, so don’t go overboard.

I hope this works for you, any questions or comments feel free to drop me a line!