Hacker News Reader

Comment by jen729w | Hacker News Reader

Funny enough, we had a hell of a time running a helpdesk where we designed the docs -- many of which I wrote myself -- to be executed exactly as written.

Guess what humans hate to do? Especially the smart ones, which of course you want to employ on your helpdesk? They just would not read the damned instructions.

I think this was because many of the instructions were dumb. We were explaining decades-old bank stuff. It didn't make sense, but it's what you had to do! So these guys tried to 'fix' it, and in doing so, broke it.

The whole support model was predicated on this idea that the 3rd level guys would write stuff that the 1st level guys would slavishly follow. It never worked.

View on HN

You could probably fix this, to some extent, by adding a sidebar to the instructions that 1) acknowledges that the procedure doesn't seem to make any sense, and 2) points out why the seemingly obvious fixes won't work. That's usually immensely helpful to me as a reader, so I don't have to waste time wondering if I misunderstood the instructions or the author misunderstood the procedure.

Joel Spolsky famously wrote in the year 2000:

    > Users don’t have the manual, and if they did, they wouldn’t read it.

— <https://www.joelonsoftware.com/2000/04/26/designing-for-peop...>

That's it! :-)

That's why I like GNU documentation. The don't explain the program, they explain the user domain model and then everything just clicks. The first time I read one of those, I was like: Where is the actual documentation? I want to skip this. But what I was looking for does not exist. This seams tedious for the first time, but then you appreciate it, because it saves time in the long run.

Maybe being able to follow a set of (seemingly silly) instructions should be part of the interview/onboarding process. And emphasised at job performance time.

Problem is a lot of times silly instructions are silly because they are wrong. Like why did you turn left and try to drive through that river? Those instructions assumed a bridge was there but it washed away 10 years ago. A new bridge exists, you can see it, obviously take that one instead.

Reply on news.ycombinator.com