This is such a good point. I've changed jobs a lot and one thing consistently bad (to varying degrees) is documentation and tutorials specifically.
"Download X and setup"
"It's not working..."
"Oh yeah, you're supposed to do it on the remote access VM"
"It says access denied"
"Oh right, you're supposed to use the Yubikey for access"
"I don't have a Yubikey, its pass + authenticator"
"Ok, I'll email Jeff from this department you wont hear off until someone new starts. But otherwise keep following the tutorial and you should be good to go!"
It always infuriates me. At my last job I had a lot more control and authority, so I redid the entire tutorial for the proj we worked on. Every few months I'd check all my account permissions, update the list on the readme, spin up Windows/Ubuntu VMs and try to get the project running using ONLY the tutorial. Anything missing - add it.
If anyone added a new dependency the documentation would be updated and the steps checked on a new VM. I did this as we had various people come in and work for a few weeks, add a new feature and leave. The end result was that instead of 1-2 weeks to get running, people would have everything running within their first day and start work sooner. Instead of needing someone for 4 weeks for ONE feature, we could finish 2-3 and sprinkle in more tests and confidence.
I think most developers would benefit from writing for a less experienced audience, especially for this sort of thing.
I've always this attitude that the one after me should not face the same issues as I had and so I update all wrong documentation, this also helps me remember how stuff works. But I have had many occasions where I just had to give up. People thought I was being annoying, my PR for fixed Readme (or even a Readme at all at times!) were simply not picked up, etc, etc.
I left that company, and left a letter for management about the abysmal developer experience.
I prefer to think that updating the documentation isn’t fixing the root issue, and that the working systems are their own documentation if explained properly, so document in such a way that they can’t become outdated, when feasible.