Documentation is always way too vague about or just plain missing critical details and too specific about things I don't care about.

In my experience, onboarding is something that is usually an afterthought, if it is considered at all. Which is why, when starting from scratch as CTO at two companies, I set it as a top priority from day one. In both instances, onboarding was optimized as much as possible. In one company, we used Okta, and 90% of accounts needed to be productive (Git, Jira, Confluence, the HR system, etc) were auto-created prior to the start date. We reduced, as much as possible, the need to manually create or request access to needed systems. Instead, based on your job function, we already knew what you would need access to and automatically made those requisitions. I realize this is easier to do when you are starting from scratch, but it demonstrates that it is feasible. It’s simply a matter of will and valuing the importance of a smooth onboarding experience. After all, you spent a ton of time and money finding this candidate - why not get them productive as fast as possible?

Setting up the development environment was also scripted. We had scripts for setting up and installing the tools needed for frontend and backend development. Common aliases and scripts were shared via a shared “dot files”. In most cases, it was possible to checkout the relevant repos, run unit tests, commit code and deploy to production on the first or second day. There is no reason one can’t have all you need ready to go on day one. Certainly things get out of date as time passes, but the expectation of every new hire was to improve the documentation and fix any flaws. This “onboarding as code” mentality also made it easier when an experienced engineer needed to set up a new laptop. Documentation is like a garden - it needs to be constantly weeded and pruned.

Finally, there’s the matter of learning the tech stack, code base and current toolset. Again, this needs to be a deliberate, well thought out experience rather than an ad-hoc, thrown into the deep-end of the pool, sink-or-swim challenge. A manager needs to make it their top priority to figure out how to get new employees (or internal transfers) up to speed and confident as quickly as possible. This requires special skills in writing good documentation and figuring out the various learning styles of engineers.

I agree - if you onboard, and struggle getting code to compile, can’t find the right documentation about how things work - then it sours your experience with the company. In some cases it feels like onboarding is a struggle and it’s a badge of honor to have survived. That you “made it through” and “paid your dues.” This may work with certain engineers, but I don’t think it is healthy or wise.

In particular, Duo for 2 factor and LastPass, and the curl command to start downloading a bunch of stuff.

FWIW I thought it was pretty streamlined, better than what I'd had in the past.

What I have learned from my time in the military is that onboarding is more important than candidate selection. Regardless of onboarding success comes down to personality. The quality of a candidate’s professional experience is more a reflection of that personality than an indication of current technical competence, which is where candidate selection is often severely misunderstood. Provided a properly selected candidate there can be enormous room for positional success if the criteria of success are well defined, documented, and trained. This is where onboarding is important. I have never seen corporate software get this correct even though the same company likely has this mastered in other career fields.

The common expectation is that some other company trained the candidate for you and that they are fully technically competent walking through the door. That is an unrealistic expectation born from poor planning and lazy leaders. The result is beginners that need tremendous hand holding and the bar of acceptance to be continuously lowered or seniors that are everything the company wants except compatibility with people who need too much hand holding.

What I’m doing now is a weekly series of recorded hands-on/whiteboard sessions, building up from the 10,000 foot view of the software (the most fundamental user journey) and working piece by piece towards the details. And I’m letting the onboarders steer the agenda - they tell me what they’re ready for next, a few days ahead, and I pull the diagrams/exercises/links/docs ahead and then just kinda wing it.

It’s more effective, and enjoyable, as far as I can tell. It’s probably not paced as ideally as it could be, but as a manager I have likited time to give to something like this. We’re getting to the point where I think some of the veteran engineers could take slices and host the discussion. And the recordings will hopefully act as an accelerator for the next batch of newbies.

I still feel like there’s a lot better a resources and time strapped manager could do.

Once I thought it's because software is too complicated, but it seems every time I lower the entry barrier, people lower their opinion about what is a problem.

What I don't understand is, that even professionals turn their brain out when setting up a system of any kind.

When I have to go to a customer and need to set some stuff up, I ensure that I can complete that task without the help of others. If some unexpected happens, I write it down at some central place and consult it the next time.

But some people just head out every time without thinking or planning.

- You can use the trial for unlimited time, and many folks do.

- We've tried onboarding that includes sample boards, but this tends to be confusing because it's someone else's thoughts rather than your own.

- There is a learning curve--we like tools take a bit of time investment, but one that will pay off with power and flexibility in the long run. vim and emacs were two inspirations here. https://museapp.com/handbook

I originally thought that I was just unlucky, but when I asked around I found that I had an above average experience, at least among people near me who started recently. Unlike many other folks, I was actually able to get a username/alias, a computer, and an office. I don’t know what folks without a username do since they can’t even start clicking through the necessary EULAs to get permissions to do stuff, let alone do any actual work.

I’m not sure how it is in other parts of the company, but if you imagine that it’s similar and do some back of the envelope math on how many people get onboarded and how much losing a month (or more) of time costs, it comes out to N million dollars for a non-trivial N. And that’s just the direct cost of the really trivial stuff. It’s hard to calculate the cost of the higher level stuff that’s mentioned in the article, but I suspect that’s even more expensive.

Joke apart and like said on other answers, onboarding is rough but will improve it.

Once you are in, you can use all the features.

I've "onboarded" (enterprisey word for orienting/registering/supporting/creating accounts for new hires) many new employees disoriented/frustrated by their new org's tools.

What often happens when a new hire really disagrees with his/her new tool for task is that they only use it for the "last mile" of the transaction.

So... say they have to turn in an expense report in Excel template. But they like some other app. They will take all their notes in $preferred_app, do all their editing in $preferred_app, and at the last step, export to Excel template.

You should see the machinations I've seen around mail. Convoluted downloading and parsing from Exchange servers with shell scripts... hah.

In any case... this is not ideal. What this does is make users absorb complexity for IT. IT can get comfortable wtih a platform, too leery to try something else. But users, often years into new generations of workflows (not just young people, so many older employees have been using Gmail for years in their personal life for example.), absorb the blow.

Oof, being a one-man show is taxing. Thanks so much for your feedback, I've added a task in Teamwork to get on this!