Easing onboarding pains

February 21, 2019

As agile teams scale, or as developers roll on and off a team, even the more diligent development teams encounter the issue of tech debt which is left behind for new people to absorb. This is a struggle for teams, particularly where often local development relies on the phrase “this works on my machine”. It’s something I’ve witnessed having rotated through several clients now with varying levels of onboarding efficiency and tech debt, ranging from a few days to a couple of weeks for developers to get up to speed and ready to take on new work.

Of course, with more tech debt and an inefficient onboarding process, getting a new team member ready to work leads to a delay in seeing the benefit of delivery and can often take a performance hit on existing team members as well whilst they spend time doing knowledge transfers.

Here are my top tips of how to resolve these issues and unlock some benefits in other areas at the same time.


It sounds like common sense and best practice to write up how your code works, how people have set up their local environments and the business context that surrounds the work your team does. However, in my experience, this is often treated as a low priority in the face of critical deadlines and key deliverables leaving documentation out of date or completely missing, as well as sometimes being loathed as a step by developers.

My preferred approach is to include a readme in the code repository. It may take an hour to document code properly and test it, yet it can save a lot of questions and set context for the existing developers helping with onboarding, helping to reduce the tech debt people keep in their heads and on their laptops. It’s worth adding this to your team’s list of mandatory activities for each new piece of work.


Automate your local development setup by taking time to write scripts for manual installations or configuration tasks and keep them in an accessible repository; don’t assume every developer coming in will be using the same operating system or have the same dependant components pre installed and configured either. An ideal starting point is to take the dependencies and steps your existing build process uses, along with any package management tools such as npm or pip, and stitch them together almost replicating what your build service does. This could be a good first task for a new Developer or DevOps engineer on your team to create and document this.

This brings other benefits such as being able to recover if you transfer to a new development machine along with aligning all your developers onto the same common ground, avoiding those “well it works on my machine” moments.

If your access control isn’t already automated or easy to use without a long winded process, it might be worth replacing the mountain of IT access requests with an automated solution to correctly provision access based on what team the new developer is in. One previous client developed their own which allowed a new member to be added to a team by an authorised team lead, then immediately be provisioned with the base level of access tokens, account passwords and access rights the rest of the team have. This will often require coordination with the various teams managing your infrastructure and tooling. It’s also a good idea to involve the security team here too. This not only enables simpler, more rapid provisioning but also brings other benefits such as clearer auditing and access control.


Unless you’re integrating with or working on some legacy services, modern applications can be easily ported to Docker containers or even virtual machine images orchestrated using tools such as Vagrant.

In fact, modern tooling and applications are likely running on Docker or Kubernetes already; allowing you to simply pull in the same applications locally that get used all the way up to production. Similar to automating your local setup, it’s worth building your tech stack into a docker-compose file that can easily be shared to orchestrate and deploy your application stack locally, allowing a platform to test and develop against safely. This can also give benefits to integrating teams allowing them to test their code against a production-like copy of your application running locally.


Teams often work in Silos, doing their own thing, using different frameworks, tooling and going slightly rogue with how they use them. Simple cross-collaboration with a weekly meetup or through the use of guilds split by key roles can allow sharing of best practices and alignment between teams. This can ease a lot of the pains experienced with moving someone from one team to another within an organisation, as often happens when projects scale up or down.

These tips might not ease some of the physical pains with onboarding and getting new team members through the door, however by following these steps you can reduce the onboarding time, essentially allowing them self-service to get up and running and improve how tech debt and other quirks with your applications are documented and shared around the team. This helps to improve the time from getting someone into the team and ready to work from up to a week or two with little documentation, tech debt and a thinly stretched team to a day or two at most. This allows everyone to focus on getting the work done whilst improving other operational areas and best practices.

Get in touch if you’d like to chat to us.

Jamie Whittingham
DevOps Engineer