Andre Liebermann
// essay03 Sep 20268 min read

Onboarding is just reading now

What I often encounter and what worked for me across dozens of teams

Andre Liebermann · @Avataw

The perils of onboarding

Starting a new job can be a lot. For the first few weeks you’re technically employed but not yet useful. Especially as a consultant or freelancer (been there, done that) the urge to prove oneself asap is strong. And as an employee I also want to impress my employer as soon as possible to reduce the risk of not making it through the standard 6 months probational period in Germany.

I’ve been through this a lot and here are some onboarding archetypes I kept running into:

Mandatory Onboarding Course

Some companies had a mandatory course spanning from 2-6 weeks. Sometimes even onsite! Of course only the bigger companies are able to afford such a luxury. But is it actually helpful?

In the ones I participated in it was great not to feel alone - the people who started at the same time often formed a sort of kinship and stayed in touch. At the same time it can also be a massive waste of time, especially when 90% of the content is not actually relevant to your specific position.

And back in the days I would not have the patience (or necessary business background) to follow hourlong discussions about seemingly minute issues - I wanted to code!

Team Onboarding

More often than not I did not start as a solo developer, instead I was placed in a pre-existing team. These teams would already have some sort of existing onboarding procedure, which can be somewhat useful, but often isn’t 1.

At the same time it’s great to be able to contribute a lot faster than in the previous archetype. I’ve personally enjoyed pairing for the first couple of weeks and gradually start implementing things by myself - especially in the beginning of my career.

It’s also important to note, that every team has their own dynamic and I’ve personally experienced the stages of group development many times. Therefore I believe it makes sense to get this process going asap, instead of letting new employees go through an onboarding outside of the actual team that they will be placed in.

Chaos Incarnate

Well and sometimes there was basically no onboarding. Especially in smaller companies, employees can feel so swamped, that they feel like they basically cannot afford to onboard new employees as a dedicated, separate activity.

Day one you are supposed to provide value and fight along within the trenches.

It might not sound like it - but I actually don’t think this is necessarily so bad!

Sometimes it’s great to be forced to take a plunge and in these cases I often felt a lot more ready and capable after 1-2 months, compared to the other archetypes.

Also when I just joined a company I want to know ASAP if I want to spend the next N years here, so the more I get to actually do from the start - the better!

My personal preference

As is often the case, the truth (or in this case, my personal preference), lies somewhere in the middle. I do always try to have a clear roadmap set in place for me with my direct manager, whenever I start working with a new company. It simply helps me to know what is expected of me.

Group onboardings can also be a solid way to get to know other departments or teams - therefore I try to participate in those as well.

When doing Team onboardings I often find myself trying to improve the existing onboarding docs 2 and less pairing nowadays - instead I try to involve myself through PRs.

On having a buddy

I also want to talk about the worth of having a buddy in any onboarding.

I personally believe that it makes sense regardless of company type or size.

You always want to have someone who is not necessarily in your team that you can ask some questions that you might not feel comfortable asking within your team.

Also just someone who checks in with you every now and then, for a coffee - this is especially important if you start remotely!

It’s often great to have someone to ask who works as a sort of gateway / proxy and can direct you to the appropriate slack channel or person to clarify.

Also especially in fast growing companies I recommend to have people be buddies who have been in the company for some time. This is the best way to keep the company culture alive and well. Nothing erodes it faster than having an onboarding buddy who has only been at that company for a couple months too.

At the same time you don’t want the extremely vital most senior people to be buddies - otherwise people are reluctant to actually reach out to them.

Onboarding via PRs

In the age of AI and e.g spec-driven-development (SDD) I found that the actual effort involved in writing code has been left- and right-shifted 3.

Left Shift

Especially in SDD with frameworks like GSD 4 handling the requirements engineering as well as any sort of technical architecture is a lot more time consuming than the actual implementation process.

I’ve personally had hourlong grilling sessions5 resulting in the actual implementation happening during a coffee break.

Right Shift

The actual testing and reviewing of what the AI produced, can often take a lot longer! Personally I feel like reviewing is all I do!

Also it’s difficult because so far I always tried to follow the Code Review Pyramid but I keep stumbling over utterly insane AI generated snippets or comments, that throw me out of the loop.

Are PRs still a viable way for onboarding?

I vote yes. It’s still a great way to get yourself familiarized with a lot of things at the same time! At the same time a PR nowadays necessitates looking at the bigger picture (although some might argue that a thorough review always included this).

I want to look at all the documents that were taken into consideration for this PR. Any prd, adr, spec-file - anything!

Read Read Read

I love reading - I truly do! And yet I’m getting a bit tired of it, at least in a professional capacity.

Nowadays it truly feels like my job mainly consists of reading AI generated documents or code. There is just too much yapping generated by AI.

And I increasingly catch myself asking AI to summarize huge AI documents!

I don’t have a fix for this. The yapping isn’t going away.

What I’ve landed on is triage6: skim everything, summarize the big stuff, and only read closely the handful of documents that actually decide something. Turns out AI is pretty good at exactly that.

Using AI for onboarding

That being said AI can also be quite nice while onboarding.

Just recently I let claude analyze my obsidian notes as well as my terminal history, to extract a proper Everything I needed to do to get started doing my job list. Unless one is extremely organized, it’s soo easy to forget one crucial setup-script.sh or some silly local proxy configuration to actually make the local setup work.

And of course - those things should eventually be ironed out and made redundant with a proper setup.

Leveraging Summaries

Another use I found for AI is actually summarizing. Honestly that might be the thing LLMs7 are best at.

And I am not exclusively talking about docs. I’ve found overall architecture summaries and lists of “most vital” files quite helpful.

One could also use AI to summarize the gitlog and look at the most commonly touched files - which can be quite helpful to identify problematic sections in the code or other bottlenecks.

How I try to organize it

Another thing I want to cover is how I actually try to organize onboarding in my teams.

First I want to clarify the expectations with the new hire and let them commit to what they want to do.

More often than not that should include heavy pairing in the first weeks.

Depending on their seniority they should review PRs (or participate in review sessions with more senior devs).

Ideally they can start working on something with as few business-specific pitfalls as possible. What is especially suitable for this is some rather technical thing that is a quick win and has been postponed for some time but everyone agrees that it helps.

This has such a positive impact on the onboarding process!

Devs feel helpful and valuable and you can practically see them stand up taller and gain confidence with every early PR that gets merged.

Other devs slowly start getting used to the new person and how they develop things.

In my teams I like to have a list of “onboarding” tickets ready for new hires (admittedly these are often end user focused and hence in the frontend as I personally believe that it’s important to actually touch the thing the company is building as much as possible in the beginning).

This is quite similar to how open source projects handle it with “Good first issues”. Also a sort of “Contribution Guideline” and “getting started” section in the repo README.md akin to open source software can make a lot of sense for any sort of company as well.

Final thoughts

I don’t think there is a universal right way to onboard and it most likely never existed.

What’s new though is that our job itself shifted towards reading, so onboarding shifted accordingly. PRs, specs and AI summaries are where it’s at right now.

Ask me again in a year though. This stuff changes fast.

If you ever experienced some amazing onboarding - I’d genuinely love to hear about it! Just drop me a line

Footnotes

  1. More often than not it would be a severely outdated Confluence page. Truly, the one constant in my career has been that information moves to Confluence to die. ↩

  2. Resulting in a slightly less outdated Confluence page. ↩

  3. I’m borrowing this left/right terminology from practices like Shift-left Testing. ↩

  4. One such toolkit - requirements and architecture first, code later. Also: I just found out they rebranded from Getting Shit Done to Git. Ship. Done. Buuuuh! Sellouts! ↩

  5. Grilling as in: the AI pokes holes in your plan until one of you gives up. More productive than it sounds. ↩

  6. It might even make sense to repurpose Matt Pocock’s triage skill for exactly this. ↩

  7. I’m using AI and LLMs somewhat interchangeably. I know. Sue me 8. ↩

  8. Actually please don’t sue me :[ ↩

<- all writing