Improve Team Experience with Developer Onboarding Documentation
Published on • 6 minutes read
You joined the new company, got a new computer, downloaded some necessary tools and today is your first day in the project. It’s already 10 am but no one is contacting you.
You skim through your Slack channels, but you can’t see anything new. After checking the calendar there is no information about any calls. You don’t know what to do and you’re currently contemplating your life choices. Maybe the previous company wasn’t that bad?
Suddenly red dot pops up on private messages. You got a link to a repository and confirmation that someone will contact you soon. You can start setting up the project.
You are not sure what are the necessary tools, but at least there is a README in the repository. You copied the command and clicked enter, but there is an error…
Sounds like a nightmare?
Good Onboarding Process Preparation #
You might be busy, or the communication from the HR team might be lagging, but something like this should never happen. It’s a Tech Lead's responsibility to onboard a new developer. The key to making a future-proof process is to prepare good developer onboarding documentation.
My Experience with Developers' Onboarding
It's here to give you a quick idea about my background, but you’re welcome to skip it.
My experience with onboarding was developed by managing R&D projects. It was a challenging environment. The biggest issue was developer rotations. I could only work with people not yet assigned to the project, but that status could change in a few days. Creating developer onboarding documentation was the only way to prepare for new developers and make sure that every team member is aligned.
Design Document, a Project Introduction #
The first intuition would be to focus on Readme, but for me, the document used to introduce developers was more important. It would be hard to do it multiple times and not miss any important information.
Is there a document that describes the project, architecture, tools, and explains the business value? Not everyone is able to pick up everything from a short call. Give your team the possibility to read information about the project at their own pace. It will be more valuable than the quickly drafted note developer did while listening to your explanation.
Readme, a Setup Document #
I won’t lie, Readme is a crucial part of onboarding. If the developer already knows “why?” now you should show respond to a “how?” question.
Make sure that you have the Readme prepared and maintained. Yes, that’s right - Readme should be maintained by the team. If that’s not the case for you, let the new joiner know what’s the current state and ask for feedback. Make sure that you did assign a mentor, who will be happy to get them unstuck when the command added to Readme two years ago is not working anymore after the dependencies update.
Ideally, you should periodically ask someone to verify if the Readme is still up to date. Make sure that the whole team is on the same page about doing updates when something changes in the project setup.
Software Developer Onboarding Checklist #
The checklist for a new team member is a great idea. It prevents missing some important parts in this busy period. There are a few things you need to remember about. Check the list below.
Tools #
Not everything can be covered in Readme. There are different tools, and new team member should confirm getting access to every one of them. Think about Jira, Documentation access, a Drive with the project files, Communication channels. Prepare a checklist which would act as a reference and a clear path to complete onboarding.
Documentation #
We already have a few files to share - Design Doc, Readme and all the other documents.
Include them in the checklist. List the ones which are crucial to familiarize yourself with before starting work. Think about business documentation, documented processes, good pracitices to follow. Gather all that and decide which are the most important. You don’t want to overwhelm. Make sure that all the links are available and it’s easy to search for particular piece of information.
Onboarding Checklist for Leader #
To be prepared at all times I created my own onboarding checklist.
It was especially important when person starting work in R&D project, was also new joiner to the company. I had to help them understand R&D purpose. Not everyone had a chance to work in such environment, which might be demanding. From day one you need to dive deep with all that unfamiliar solutions and technologies.
I had to make sure they know that their status might change. When switching project it meant that their work would be passed on to another developer.
I compiled an onboarding list to get new developer up to speed quickly. I also had to prepare a few things before developer was onboarded. Below, there is a list of the most universal items.
Prepare a Task #
Always prepare a first task for a new developer. Don’t leave them hanging, do not pass this responsibility to another developer.
It feels awful when you want to learn a new codebase, but the ticket is not yet prepared for you.
It can be an easy task, even a small bug fix should do the trick to get to know how your processes work. Apart from codebase, developer needs to learn how communication works, what’s the git flow, how to trigger CI/CD. Simple task is enough to get familiar with that.
Prepare Tools #
You should explain tools in the Newbie Checklist, but requesting all the necessary accesses should be done in advance. It shouldn’t be much work. It will be a great help for an already confused developer trying to go through your documentation. It will save some time and allow developer ship value quicker.
Prepare a Calendar #
Developer should already be familiar with tools and processes around the code. Now you should invite them to the necessary meetings. It's important to explain their purpose too.
It will be a good idea to introduce team members and stakeholders in advance. It will be easier to actively participate in the meetings.
Prepare a Point of Contact #
You already explained everything, but did you decide who would be a point of contact for your new joiner? Are you able to assign a mentor from the team for a first weeks when developer gets introduced to codebase?
Make sure that both mentor and mentee are okay with unlimited amounts of questions. New developer shouldn’t be embarrassed to ask questions to get up to speed with a team.
Make sure that person mentoring has space to do it. Go easy on them. Make sure that their sprint is not overloaded with work, and there is enough time for them to schedule calls.
Summary #
Creating developer onboarding documentation in advance will be an immense help. It will allow developers to ship code in the first week.
The key is to explain all the parts of documentation, and then allow them to read it on their own.
I hope this article explained the developer onboarding best practices and inspired you to prepare documents and checklists.
What is your experience with creating developer onboarding documentation and onboarding new team members? #
Let me know your thoughts on Threads - @this.dev or Twitter - @IdaszakDaniel.
Tweet