Wikipedia defines onboarding as the mechanism through which new employees acquire the necessary knowledge, skills, and behaviours to become effective organizational members and insiders.
I started a new job recently with what I believe is an awesome company. I am a new hire at a company again, so I am going through the onboarding process again — one of the best onboarding processes I have ever gone through I must say. This got me reflecting on the onboarding experiences I have had.
The goal of the process is to get new hires up and running as fully functional and autonomous members of the team and the company as fast as possible. Therefore, it is important to ensure that all the onboarding materials provided to them is as easy to parse as possible and makes this process as efficient as it can be. Unfortunately, this does not always happen, this article is a short compilation of some onboarding frustrations I have experienced in my Software Engineering journey. I hope it will help you improve your processes. I also hope that only a few people can relate to my experiences.
This is in no way exhaustive and I may come back in the future to add more things if I learn or remember something else, or I will write a follow-up blog with the new things (the second idea is probably the better one). With that out of the way, let's go.
All the acronyms and abbreviations
Reading a document with many abbreviations and acronyms that are not explained can be a big pain and can make one feel like an outsider. You must search through alternative company documentation or contact a team member on every turn which adds some serious drag to the process. So do not assume context, linguistic or cultural-based familiarity. When you mention terms that do not have a commonly known meaning outside your company, explain them, do not assume that everyone knows them, particularly in onboarding document. Extra points for explaining their meaning as close to where they're used as possible. Needing to refer to a separate document just to get the meanings of words and acronyms can add also add some unnecessary friction. If defining in line is not possible for some reason, then a supplement or definition of terms section at the beginning or end should make easy reference.
... do not assume context, linguistic or cultural-based familiarity.
Therefore, explain as much as you can. After all, we software people speak a lot about readability when referring to writing code —- writing meaningful variable names, avoiding abbreviations that aren't commonly known, explaining complex logic in source comments, giving the context of changes in commit messages, etc. —- so the understanding of efficiency gains when things are easy to read are well known to us. Let's not forget that in onboarding documentation. Do this when talking to new people as well. This is even more important with global teams where people have different native languages and cultural contexts.
Paying that extra bit of attention will help create a culture where newcomers and people outside your immediate team can feel like, 'yes, that's for me too'.
So many assumptions
As you craft your onboarding documentation, realise that your new hire probably does not know much about the product or project they will be working on. They have no historical context for why things are the way they are. They are not familiar with the team’s choices for various processes such as code reviews, version control management, release management, and countless other things. And they don’t know about random idiosyncrasies that have been adopted by the team over time, things that are probably not documented but people just "seem to know". Without that little additional context that everyone seems to have, a lot of technical content can feel just a little out of reach even for very competent people and exclude them from being able to participate as fast as they could.
I know, I know we are engineers, and we are hired because we are supposed to know what we are doing but it does not take long usually to be clear on as much as possible and not to assume that someone knows something. Even when dealing with an experienced engineer, offer to walk them through how the version control process works at this company. Let them be the ones to turn down the offer if they do not need it. That added bit of helpfulness pays off with dividends down the line.
Without that little additional context that everyone seems to have, a lot of technical content can feel just a little out of reach even for very competent people
Consider that the meanings of things can change over time and the terminology used for a given subject can also change over time. So even if the 'Voldermort Pipeline' means something to everyone today, the context that gives it meaning might be lost in a few years. If that happens, all the witty documentation you wrote without explaining things could become difficult to parse for everyone. So, avoiding assumptions in your documentation is useful for more than just easing the process for new hires.
No more tests, please
If the hiring process was done right, you should have already decided whether this is a suitable candidate for the job or not. If other things need to be figured out, you have the entire probationary period to reassess your decision. Therefore, onboarding time is not the time for random quizzes and knowledge tests. Your new hire is already burdened with the task of learning this new company, this new team, this innovative technology, this novel approach, etc., the last thing they need is to attend to a random spot check of their knowledge.
"There's no need to say, 'apply pressure to the right side of the mouse', when 'right-click' would do." - Aer Parris
Research shows that accessible design is good for everyone — even people without disabilities or impairments. For example, auto-complete initially made for people with low dexterity, is now widely used by all and contrast and colour guidelines, created to help people with vision impairments, help us all see better. The same is true for writing documentation. Sure, your teammates are smart people with above-average reading levels, and you want your new hires to have the same intellectual acuity, but they are also busy. So, do everyone a favour and save them time by not making them have to parse complicated language and sentence structure. In the words of Aer Parris, "There's no need to say, 'apply pressure to the right side of the mouse', when 'right-click' would do."
Summing it up
Writing good onboarding guides may take more time up-front, but it pays off down the road when new members of the team can easily and efficiently get up and going and contributing to the work. After all, your new hire is already buckling under the weight of tonnes of things they need to get familiar with in this new place, help them win back some precious mental headspace to get work done.
Forming highly efficient and highly functional teams is ultimately about building a community, and communities need to be sensitive to the needs of potential new community members. However, community is the most complex part of building a team because it is the most abstract. You cannot solve it with algorithms and formulas, you need to pay attention to things like empathy and inclusion.
Forming highly efficient and highly functional teams is ultimately about building a community, and communities need to be sensitive to the needs of potential new community members.
Finally, your latest hire has the best knowledge about how good your onboarding material is. If making the time to fix up your documentation is difficult, allow them to update the parts that they found hard to follow while their experience with it is still fresh. That way, your documentation will get better with every new hire and stay up to date since it is highly likely that some things have changed since the guide was written.
Is any of this stuff relatable? Do you have any of your thoughts and experiences to share? I'd love to hear them in the comments below.
