Hacker News Reader

Comment by IanCal | Hacker News Reader

I worked with someone who was great with this. They’d go through the docs and do exactly what was said, document where problems were hit and then repeat from scratch again and again. Seemed slow but their docs were excellent and I’m sure it saved more time having him hit each thing once than everyone else hitting them loads.

View on HN

I am that guy. I will also say from experience: It does not pay. Never once has it been ack'ed in a year end review (which controls bonus, salary increase, and promotions). As soon as a manager sees you as "The Wiki Guy", they take you for granted. As I grow older and more cynical, my view on internal docs: (1) Write them for yourself. (2) Write them to make people go away when they ask you questions ("Did you search the Wiki?").

I had this issue during a job interview exercise. Their "follow these steps exactly" were simply broken. The root cause was that they were having people re-use the same shared remote amazon desktop system. Each candidate got their own home directory, but they wouldn't just reset the image between candidates. The person before me had used up 98% of the drive space. When I followed the 'step by step' guide, nothing worked, because it was out of drive space, but... I wasn't seeing 'out of drive space' messages directly - I was seeing their 'setup shell scripts' looking like they worked, but then nothing did.

I honestly thought this was some sort of trick exercise to see how I deal with broken processes, and I was writing fixes to their docs and shell scripts to deal with error states, and reported back to the person. I initially got a 'no, this isn't that sort of test. the docs work, just follow them'. After more back and forth, I got 'oh, I see that might be broken, yeah, just carry on'. I fixed what I could, made a couple commits back up, but was then told my commits needed more context, which I then added, and promptly never heard back from them again. Until... weeks later, HR reached out to say "we've gone with someone else". I recounted this story and got at least some semblance of feigned shock of 'that's not how any of this is supposed to go'. I'd kept some screenshots and emails, but they didn't care to go down that road.

tldr - Employers giving tests, please run through your own exercise processes now and then (or maybe even automate them with some smoke tests).

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.

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.

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.

Reply on news.ycombinator.com