Onboarding Software Engineers — Beyond the Corporate Swag

The onboarding experience for Software Engineers is an important part of DevEx

If you’re on LinkedIn, you’ve undoubtedly come across a post about how someone is excited to join a new organisation along with a picture of swanky corporate swag. While this is certainly a good way to show new joiners that your company is a great place to work, this is not the onboarding experience I will be discussing in this post. Instead, I will be delving into the journey a new engineer has to take from day one at the organisation to committing a useful piece of code, having it reviewed and merged. This process will include setting up the necessary hardware and software, and providing access to necessary tooling. Depending on the nature of your organisation, the process could also include setting up security software, VPNs and putting the new engineer through compliance training. All this can take quite a bit of time and results in the loss of productivity. I have observed such journeys taking anywhere from a couple of weeks up to a month. To me, a good benchmark is having a new joiner fully productive within a two week sprint cycle.

Setting up tooling and access are the more obvious factors, but we should also consider the time and cognitive overhead it takes for a new joiner to understand your codebase and the design patterns used in it before they are able to contribute something useful. No new joiner wants to have a hundred comments on their first pull request. On that note, consider all the other non-coding functions that one must complete to get their contributions merged, like reviews, ensuring that builds pass, packaging, deployment, etc. In large enterprises, figuring all of this out might take another month, which is another month of lost productivity.

The trick to creating a great onboarding experience is conscious design.

You should start by breaking down the complex onboarding journey into smaller milestones and define metrics on what would constitute a successful journey. Some examples could be, the time it takes for one to be fully productive, how many times one requested help, etc. You should also collect feedback at the end of the journey. Borrowing some concepts from our friends in the creative department, you could even conduct some unmoderated usability testing from time to time.

With the journey and the milestones in place, iteratively build a set of self service documentation and resources and test them against the metrics you defined earlier. Self service is key here. Concise, well designed, easy to consume documentation is a valuable asset, primarily because it eases the burden on other engineers of having to guide new joiners.

Content may vary by circumstances, but here are some good ideas:

  • A write up about your engineering values to start everyone off with the correct mindset
  • Environment setup guidelines
  • Index of the tooling and how to gain access
  • Repository structures, design patterns in use with reference to a model PR, index of code owners
  • Communication channels and team calendars
  • FAQs

I’d also recommend keeping documentation as close as possible to the point where it is needed. While Confluence might be a good place to document an index of important tools, coding guidelines and design patterns should be part of the relevant repository README. Tools like Swagger UI, Dokka, Jazzy, and JSdoc are great for automatically publishing code level documentation. Docsify is another good open source tool to publish documentation written in Markdown, with all the goodness of version control and peer review.

After allowing some time for new engineers to consume this material, the best way to ramp up their productivity is to get them to actually start doing the work. However, this doesn’t mean that you throw someone in the deep end and hope they turn up on time for Sprint Demo two weeks later. While this seems painfully obvious as a ‘what not to do’, I have seen this happen. Even a seasoned engineer will require some time to adjust to a new codebase and different ways of working.

Pair programming on small tasks with the new joiner in the driving seat is a great way to make that adjustment period a pleasant one. From the navigator’s seat, there is opportunity for you to identify the gaps a new joiner may have and plan on how to appropriately address them. Pair programming is also a great way to reinforce the use of self-service resources if there are questions from the new joiner. In the driver’s seat, a new joiner will get the chance to accomplish a task faster than they would have been able to if they had been left solo. This sense of accomplishment will keep engineers motivated through the early adjustment period.

While the benefits of pair programming are clear, the right pair programming experience is a difficult one to pull off.

Challenges of power dynamics are particularly relevant in the context of pairing with a new joiner. It’s a topic deserving of its own post, but for now, you can find an excellent summary in this excellent series of tweets by Sarah Mei. The key point that navigators should understand is that this is about empowering new engineers to contribute independently. It is an investment to be made for less review overhead and fewer redundant queries in the future.

As these new joiners grow and mature through your organisation, keeping them incentivised to contribute towards the onboarding of others, by adding to documentation, process improvements, pair programming, etc., is what will create a self-sustaining loop.

Note: DevEx is a key interest for me at Aleph. Onboarding is just the tip of the iceberg. I believe that DevEx should be held to the same standard as that of the product UX you’re building. What else constitutes good DevEx? Leave a comment below!



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store