simplifying onboarding to the team
Hi! This is Masha, a technical writer in the Ozon documentation group. We do internal documentation in the Search, Recommendations, Advertising department, which includes 40 development teams. Our department is constantly evolving, new teams and people appear who need to quickly integrate into the company and the team. Recently, one of the teams was planning to recruit new employees, and colleagues asked to help make a welcome page for newcomers – onboarding.
To make the page useful and simple, we talked to the teams and developed an onboarding page. It turned out so good that we made a universal template out of it, which we use ourselves and which we want to share. It will be useful for any IT team: developers, testers, technical writers, product managers, project managers and other specialists.
Download the template from the links:
Options for how to design onboarding
Much has been written about onboarding processes, and HR specialists can tell you more about them. But onboarding is an extensive process, and each team has its own nuances. To take them into account, it is better to take everything into your own hands and create a Wiki page for the team with regulations, tools, and instructions for obtaining access. It will take a couple of hours to fill it out, and it will help newcomers navigate and ask fewer “stupid” questions at first.
Such pages are not always useful and beautiful. For example, a hastily put together onboarding may contain too much or too little information. If there have been no newcomers on the team for a long time, the information on the page may be outdated. By the way, this is one of the reasons why teams refuse to create pages for newcomers and transfer information “upon request”. We do not condemn this approach, but understand. Maintaining a page when hiring one employee per year is unproductive; it is faster to call and tell everything.
But if there is one newcomer per week or month, team onboarding makes life easier. We decided to help our colleagues from the department and develop a template for a welcome page. To make this template as useful as possible, we studied the pros and cons of different types of onboarding and chose the best option.
pros | Minuses | |
There is no onboarding page | – No need to keep up with the times. – The mentor is more involved in the training of the newcomer (but not always). | – Important information is transmitted personally and is not recorded anywhere. Because of this, the mentor may forget to transmit some information, and the newcomer may be stressed that he did not remember everything. – A mentor may not pay enough attention to a newcomer due to his workload, and the training and adaptation period will be extended. – If the knowledge holder resigns, all the information will disappear along with him. |
There is an onboarding page put together by the team | – The information on the page will definitely be useful for a beginner. – Important information is in one place – just provide a link. – Reduces the stress level of a newbie. | – The page has a chaotic structure (but not always). – Too much or too little information (but not always). – If newcomers join the team rarely, the information is not updated. |
There is onboarding using a template | – Fixed page structure – the author will not forget to add the necessary blocks. – Easily adaptable – some blocks can be removed or added. – Important information is in one place – just provide a link. – The stress level for the author and the newbie is reduced. | – The information needs to be updated. |
What problem were you solving?
Task: to create a useful page for newcomers with a clear structure. Ozon is a large company, we started to research similar pages of other teams in search of best practices. We found many cool pages, but none of them solved all the issues of our department. Therefore, the idea arose to create a universal template that would be useful for any development team.
To implement the idea, we identified the criteria for the optimal option. So, the template should:
remind about important blocks;
have a common pre-filled section – this will make it easier for authors than writing from scratch;
adapt to the specifics of the teams.
How did they do it?
Based on the onboardings we saved as references, we moved on to creating the structure of our template. In the book,TED-Style Presentations: 9 Techniques of the World's Best Speeches” they write that the ideal presentation consists of three large blocks, which are divided into three sub-blocks. I thought, why not use this technique to create a template, how is onboarding not a presentation of the company and the team?
This is how the structure of the first version was born, consisting of an introduction with a short story about the team and blocks:
“First Actions” is a block with checklists that suggest what needs to be done on the first working day, week, month, or during the probationary period.
“Resources” is a block about chats, tools and projects that the team works with.
“Additional Materials” is a block about the organizational part of teamwork with useful links.
To understand how useful the template was, we tested it on the onboarding pages of several teams. This is how we found out that the structure needed some improvement: not all of the pages had enough material for the first tasks, information about resources was located chaotically, and other difficulties arose. Also, there was no room for documentation in any block. As technical writers, we could not allow this. After all, if you are going to instill a culture of documentation, then do it “from the start.”
In general, after several iterations, we came to the very version of the template that we want to share.
What happened
In the final version, we kept the structure with three blocks and three subblocks in each, but also added a single block at the beginning and end. The page looks neat and clear:
See how the template looks in real life link.
If you downloaded the template and have questions about what the author wanted to say, use the table below. It contains the final structure with the problems that the blocks solve and explanations of what should be inside. We are considering a template for development teams, but bOMost of the blocks are also relevant for other IT teams without adaptation.
Important! If there is already a manual for a specific tool written by the responsible team, do not copy the text from it. It is better to attach a link to the source – this way you will remove responsibility from yourself if something changes.
Problem | Which block solves the problem? | What's in the block |
The newbie doesn't know anything about the team. | Greeting | Introduction to the article and description of the team's areas of responsibility. |
The newbie does not understand what he needs to do in the first days and gets lost in the flow of new information. | First of all | A list of things a newbie should do in the first days. |
Tools for work | ||
A newbie is not aware of what software is approved by the company's information security specialists. He may install a program that will cause problems for the company – for example, pirated or vulnerable software | Programs to install | Third-party programs that can and should be installed on work equipment. |
A newbie is not familiar with the tools that the company has developed. Learning about tools as you go is not the best practice. You may need access to something right here and now, and a newbie will not have it. | Company tools | Tools developed by the company, such as test and production stands. We also describe how to access these tools. |
A newbie doesn’t know what tools are used in the company – access problems may arise at the wrong time | Other tools | Other tools the team uses, such as Airflow. We also describe how to access these tools. |
Resources | ||
A newbie is lost in the chats and channels he was added to, doesn't know where to look first. Important information may pass him by | Chats | A list of chats and channels in which the team or related teams communicate. |
The newbie did not save or remember which repositories the team works in. You will have to clarify everything with your colleagues and get access to new repositories separately | Projects | A list of code repositories the team works in. We also describe how to access them if they are needed. |
A newbie doesn't know what charts and metrics to look at when a feature is rolled out | Charts and metrics | A list of important charts that the team monitors. We also describe how to access them if they are needed. |
Teamwork | ||
The newbie doesn't understand how shifts are organized in the team | Duty roster | Regulations and duty schedules. If there are no on-call shifts in the company, this block can be replaced. For example, with a team meeting schedule. |
A newbie can't find the rules of work. For example, when is it allowed to release new features: he will release on Friday, but the company prohibits this | Work organization | Basic organizational issues of teamwork. For example, deployment rules, writing release notes, etc. |
A newbie does not want to waste time on documentation. All accumulated knowledge will be stored in his head | Documentation | About the documentation process in a team. If there is no technical writer and you don't care about documentation, replace this block. But we won't tell you any replacement options 🙂 |
A newbie wants to learn more about the team, tools or processes | Useful materials | A list of useful books, speeches or other materials for employee self-development. |
Of the 40 teams in the department, we have already implemented this template in ten, received good feedback and are not going to stop. But here we need to reveal a little secret.
When we created the template in the Confluence space, we went for a trick and added a selection of common tools and resources that everyone uses. It is easier to fill in such a page, because it already has pre-filled useful information. We also left hints in the editing mode – they help authors understand how to fill in a particular block. Colleagues who made a page using a template with hints really liked that some of the information was already filled in for them – there was very little work left.
How to design in Confluence
If you're building an onboarding page in Confluence, we have a couple of tips to make your life easier.
In order for everyone to use the template, it must be created in a template format in space. Then each team that uses the space will be able to create a page for a newbie using a template and fill it out. This will save time: the template does not need to be searched, copied and deleted from it information that is irrelevant for the team.
In addition, you can insert hidden hints for authors into a template in Confluence – they will be displayed only in page editing mode.
Onboarding articles can be tagged as “onboarding.” This will make it easy to find all articles for newcomers and quickly update them if a process changes across the entire company.
What's the bottom line?
An onboarding page template will make life easier for any team — no need to think about what to write and how to format it. In addition, if teams have similar work tools or processes, they can be spied on and brazenly copied from colleagues who already have onboarding ready.
Also, the onboarding page will be useful not only for newbies, but also for veterans. The information is structured, instructions and links are stored in one place – who would refuse that?
