▲ 6 points

Ask HN: How do you prepare onboarding material for new joiners?

by mmarian·2y ago·4 comments·view on hn ↗

I’m a senior engineer and I often have to show new joiners how to use our various internal tools. I’m struggling to figure out what’s the best way to create this material, and organize it.

I mostly create Confluence pages, but it takes time to write them out. And the horrible search functionality, combined with the tons of other content we have there, makes it next to impossible for the joiners to find them.

I occasionally screen record videos using Slack, but I don’t know where to store them - README inside the related repo, or Confluence. And the joiners can’t search for them.

Any other people out there who’ve faced this problem? How have you gone about solving it?

4 comments

I've used a newbie notes file for years. Mostly written but screenshots and video if they make sense. Preferably in something version controlled.

One of the first tasks of any new joiner is to update the notes with any errors or omissions. That should mean the notes are only as outdated as the last person to join. Which if you have a steady cadence of people joining shouldn't be too bad.

Having a buddy to answer any questions is good. Budget that taking 30% of that person's time at least initially.

Makes sense. We have joiners once every 6 months and we tend to work on greenfield projects, so the docs get out of date pretty quick. I could try to emphasize more to the joiners to keep them up to date; unfortunately I'm not their line manager. Thanks!

Here is what I got from multiple onboarding experience. The only good one is at Unity Technology BTW, though I think it can be improved.

1. Have an onboarding package including a checklist and links to some company/team wide documents. Ask the onboarding person to update the whole package once they went through the whole process. It's fine to leave stuffs out because company and team evolve.

2. Setup an onboarding buddy with some sessions and let the onboarding person shadow. It's a lot better than throwing a huge amount of documentation and wish good luck. Recorded sessions are also useful for future onboarding process if people are too busy.

3. Allow people some time before throwing tasks to them. And start small. I don't know why but most of my first assignment was complicated enough to take more than 2 weeks to complete. I'd expect a few days at most. A lot of the time was wasted in processes that I was not familiar with.

4. If you want new employees to be more independent, be very clear about what does that mean. Don't just say "I'd like you to be more independent", but say "If you want to do x, y and z, you can make calls without consulting anyone, but do be careful with j, k and l.". In general, be detail about team culture. I have been burned by going either side (too independent or not enough) previously.

Going back to OP's question, I believe the best thing to do, if you don't have a lot of time, is to simply let the new people shadow you while you are taking out some tasks, and record the sharing. You definitely already have some internal doc about internal tools so that should be good enough. If the internal tools are too complicated to be shown in one session, maybe multiple sessions. You can complement this by hand holding them for the first time as well. IMO you should be given the time by management. If it's difficult to search, gather the links into an Excel sheet.

A bad onboarding experience has a long shadow and usually dictates whether I'm going to hop to another job in 6 months.

Appreciate the detailed answer. The onboarding process you outlined would be ideal indeed (especially #4!). Unfortunately I have neither the resources/power nor the political capital to demand them.

So I end up with the compromise you just mention after the points, but doing it lagged, which means they're sometimes very slow in performing some tasks and they don't ask whether there's a better way of doing it.