Hacker News Reader

Comment by ctkhn | Hacker News Reader

It's crazy how bad most onboarding docs are for corporate teams. I think it's a great first look the culture and how much of a hassle the role will be. The last three teams I've joined have been brutal with how little was documented or how out of date the docs that did exist are. I've had to spend up to two weeks tracking people down to find out what access group I need for our logs, deploy pipeline, etc. and I end up writing up a new doc that's good for its point in time, immediately becomes out of date when someone adds a new system or access group but doesn't document it anywhere. The one team I was on previously that got me everything I needed in about two days was great, but it's sad that this isn't the norm. Everywhere else has been pretty hostile to getting set up, and the poor onboarding experience has been a preview of the developer experience. My current role is standing up a new devex team which I'm hoping turns the tide here.

View on HN

It's not very crazy to me. Most corporate teams are overrun with feature creep that "is very simple" (i.e. it takes 3x as long as estimated, because the codebase is a mixture of overengineered spaghetti for that one customer with edge-case requirements and legacy, combined with tests that are meant to be run in a jenkins job which takes 4h to complete).

Then, the engineers are expected to write the docs in between these tickets, and doc is seen as something "to be done within 30 minutes" - of course the docs will be comically (or tragically, depending on your perspective) bad.

Most people have 0 idea on how to write good docs, so in 30 minutes, they write stream-of-consciousness docs and return back to the ticket hell.

Most places I've been could have been upgraded with stream of consciousness. It's not surprising that they aren't all perfect, and the one place that was done to a very high standard was properly overdone, but at most places whatever counts as onboarding docs either doesn't exist, is essentially unusable, or directs me to legacy things that on day one I don't know enough to not bother with

if you're writing a new doc to "fix" this situation, you're commiting three crimes: 1. all that old documentation still exists, misleading and confusing people. you've now made the problem n+1, 2. there's no strategy to keep your new document from turning into an old, stale & out-of-date document for the next person, 3. you've addressed the wrong problem (nothing's documented!) and feel like you're superior to all the jerks who came before you.

>> My current role is standing up a new devex team which I'm hoping turns the tide here.

I'd love to know what you're doing different that can help with this problem. Writing more, new documentation is unlikely to be it.

You're right that it's not a complete solution. The overall process on this team aren't good (we never do a retrospective, ever) and I don't get to decide how we solve #2 and #3. The best I can do is bring things up to date, keep it up to date as I run into new info or we add new systems to access, and hope that future new hires are smart enough to check created and last modified dates on documents to find the most recent one.

Sometimes I wonder if it's a respect or control issue. I once worked in a non-technical position that interfaced with a complex order management system. We were given zero access to documentation and had to rely on trial-and-error and the reverse-engineered model held in the head of one specific supervisor. I'm almost certain that certain errors that appeared over and over were caused by us temporarily clearing previous ones incorrectly. This was especially frustrating because we were 2nd shift, so dealing with those errors could mean the difference between getting home that night or getting home the next morning. It was hard to tell where along the line between, "They're not sophisticated enough to make use of them," and, "We don't want our processes leaking," we fell, according to the higher ups.

My mother worked in engineering back in the late 80s until early 2000s and always told me about people who didn't document things because they wanted to be un-fireable. I didn't believe her or take it too seriously until some of these more recent teams, but I think it is a lot more common than it should be.

A technical writer's first task is to start the document that onboards the next technical writer.

Reply on news.ycombinator.com