Documentation isn't why your onboarding sucks

Some organisations have great onboarding processes, others not so much.

Having experienced onboarding with many clients over the years, I want to share what a good onboarding process is for an engineer.

Why it matters?

Onboarding is the first impression a new employee has of your company. It's the first time they get to see how you work, how you communicate, how you solve problems and how you treat your employees.

A new employee will form an opinion of your company based on their onboarding experience. If it's a good experience, they will be more likely to stay with your company. If it's a bad experience, they will be more likely to leave.

I know when starting with a new client, imposter syndrome kicks in. The faster I feel like I'm adding value, the more confident I can be about doing the job and if I'm going to be able to fit in.

Do it yourself

Being told there isn't any documentation and that you should write it yourself as you learn doesn't work. It's a terrible idea and a waste of time, as you'll be writing without knowing the rationale, or constraints the team had when making decisions.

More often than not, the fact you are writing the documentation yourself means you may struggle to help find people to answer the questions you will be asking.

Needle in a haystack

Reading outdated confluence pages can be very frustrating because, in my experience, the author didn't write with the intent to take the reader on a journey. So if the pages don't follow a structure or are organised in a way to understand what to do or where to go next, you may end up reading endless amounts of irrelevant information and feeling lost.

Jira Tickets

Trying to learn by piecing together Jira tickets as an onboarding exercise can also be futile. With similar problems to reading confluence pages, there's no way to know if a ticket is still relevant and have any confidence the actual implementation accurately reflects the acceptance criteria.

Self-documented code

No doubt you've heard the saying write once, read many times. Reading code might work in simple cases, and it can be an excellent way to understand some of the team's standards and how to structure and organise code. However, it doesn't help explain the why behind the implementation. In addition, it doesn't give information on what role the code plays in the organisation's architecture.

Unit tests

Unit tests ensure code works in a particular way under various conditions. So while they could help with learning, they won't have written in an onboarding friendly way.

End-to-end tests

End-to-end tests can be helpful when written in collaboration with people who understand the business needs, such as product owners. Then especially in the form of specifications, they can be relied upon to act as a data source to understand product requirements. However, this won't help in understanding the role this plays in the grand scheme of things or the product vision.

Pairing

Pairing is a great way to onboard a new team member.

This doesn't mean hand-holding through the codebase, but it does mean explaining the problem and the implemented solution.

It's also a great way to get to know your new team member and for them to get to know you.

Depending on their experience, your ability to communicate, how fast they learn and the complexity of your code base and architecture, you may need to pair for a few days or a few weeks.

There should be breaks to work independently, so they can get a feel for the codebase and the problem they are solving.

Onboarding shouldn't just be with engineers

New team members should spend time understanding the product and expected outcomes with product owners and stakeholders. Otherwise, they may find it difficult, if not impossible, to understand the vision, value and purpose of the work the team are doing.

Domain experts should be involved in the onboarding process as they can educate and provide guidance on domain boundaries, events, and business rules within the organisation using a ubiquitous (vocabulary shared by everyone involved in a project) language.

If anyone in your organisation knows rather than thinks how things work, it will be testers. Testers should be able to take you through various scenarios to show the rules and constraints of an application. So while product owners can describe a feature using a user story, testers should be able to verify and demonstrate the implementation of that feature.

So, what is a good onboarding process?

There isn't a silver bullet of doing just one thing for a great onboarding process.

A good onboarding process will be a combination of things, but without a doubt, team culture and collaboration are crucial components of a great onboarding process.

While collaboration may slow down productivity in the short term, the team will be more productive in the long term, with all team members understanding the "why" and how they can make valuable contributions.