How to Write an Onboarding Doc
When visiting a new country or city, a tourist guide is invaluable. It offers a quick overview of local customs, top sites to see, how to get around, a pull-out map, and the places to find the best food. Every software engineering team should have a similar guide to welcome new team members. Most teams aim to grow. Even when the team is not growing, attrition ensures that existing members get replaced with newcomers who have to start from scratch. Do you have a “Lonely Planet” guide for them?
Joining a tech company usually follows this pattern:
- All new hires join on a given day, preferably Monday. They get a general introduction to the company, sign legal documents, receive a badge, and set up a laptop. This session usually takes one day.
- Engineers do an engineering bootcamp. The bootcamp introduces new-hires to technical architecture, front-end, back-end, storage, observability, coding, and code reviews. Some of this training follows a classroom style, while others are hands-on. In some companies, such as Google and Uber, this is a multi-day event. At other places, such as Facebook, it can be a multi-week event.
- Engineers join an engineering team. At this moment, the actual onboarding starts. It is also the least structured in general, as this third phase of the onboarding process is now left to the team itself and is not organized by “professionals” in the company. To facilitate this process, a focused Team Onboarding Doc is needed.
To give you an idea of what an onboarding document may look like, below follows the general structure that was followed by some of my teams.
Introduction
The first section contains the introduction to your team and should give the new hire enough context to learn about the team’s reason for existence, who is on the team, and where the team is physically located in either an office or remote situation.
In the introduction, you have to describe your team’s mission. Formulating the team’s mission is an “interesting” communication exercise. I have done multiple team exercises where I had each team member write down their version of the team mission statement. Try the same experiment with your team. You discover how many different views you identify. This exercise comes down to clarity. It is crucial the whole team understands and agrees with the team’s core mission.
Team Members
To make it easier for new hires to recognize their new team, on one of my recent teams, I added an org-chart that shows the sub-teams and how we relate to the rest of the company. Here is the anonymized version of the latest org-chart I drew for my team:
The org-chart shows the parent team, the sub-team, and the Director/VP/CEO reporting hierarchy. Of course, it is OK for you to use a less visual and more textual version. The point is that you make an effort to make the new hire feel anchored in the big org as soon as possible.
The critical elements in the diagram are the teams, the faces, and the names. Organizations also tend to have internal tools where you can automatically create such diagrams. However, realize that most teams are structured informally, which may not be reflected clearly in the tool.
Location
For providing a sense of location, I included an actual map of our office floor plan:
This map acts like the pull-out map in the Lonely Planet guides. It provides the new hire directions to the essential elements on the floor, such as toilets, micro kitchen, fire escape, and elevators and stairs.
I always make an extra effort for each new team member to take them on a personal tour of the whole building to show them other sites of interest, such as the micro kitchen that has the best coffeemaker, the floor where other teams sit, or the roof deck with the great views. I follow the advice by Dan North for building effective teams by using the principle of “Warm Welcome” .
On my welcome tours, when walking by other engineering teams, I make an effort to introduce the new hire by name, explain their role, and name their team. At the same time, I say some words about the team we are visiting and share them with the new hire. All these efforts help make the person feel part of a bigger whole and make them feel welcomed in their new company.
Five Day Team Boot Camp
Every new hire of any level is overwhelmed the first few days of their technical onboarding. Therefore, the second part of your onboarding doc should contain a highly scripted, methodical introduction to the technical aspects of the things your team produces. These should be concrete instructions with documents to read and code labs to run.
Each new hire should have been assigned a “buddy” on day one. This person helps them proceed if they get stuck in any of the onboarding scripts. Essential is that the code labs cover the most relevant elements of what it means to be an engineer on your team.
It is vital to make new hires celebrate victories early. So, ensure they pick up a real bug, fix an actual thing, and release something into production on one of their first days. It is highly empowering when the new hire can say they released code to production in their first week.
More Information
The third and final section of the onboarding doc contains general links to topics that are relevant to the domain of your team and specific cultural agreements, such as what agile process you follow, how to take a vacation, and the working from home policy.
Format
The onboarding document can be a physical document. It can also be a wiki. It can also live in your repository. At game companies, it may even be a mini-game people “play” during onboarding. In some organizations, the onboarding doc is public and functions as an open and transparent employee handbook. Such a handbook tends to focus more on general company policies rather than team specifics. However, it is worthwhile checking out a couple of them. Such examples may provide some inspiration when you are writing your own team’s onboarding doc.
When to Start
As a final observation, you should start your team’s onboarding doc as soon as possible. You may still be forming your team and think there are more urgent tasks to consider. However, an early investment into the onboarding doc pays off.
Here is the recipe to create an onboarding doc:
- Nominate one person in the team as the owner. Maybe this is you.
- Create the doc and record as much knowledge as possible.
- As soon as a new person joins the team, assign the doc to them.
- The newcomer puts their name on top of the document.
- During their onboarding, it is their responsibility to update the doc with new findings.
- When another newcomer arrives, ownership of the doc transfers again.
