▲ | jen729w 5 days ago | ||||||||||||||||
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. | |||||||||||||||||
▲ | ptx 5 days ago | parent | next [-] | ||||||||||||||||
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. | |||||||||||||||||
▲ | throwaway2037 5 days ago | parent | prev | next [-] | ||||||||||||||||
Joel Spolsky famously wrote in the year 2000:
| |||||||||||||||||
| |||||||||||||||||
▲ | 1718627440 2 days ago | parent | prev | next [-] | ||||||||||||||||
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. | |||||||||||||||||
▲ | polymatter 5 days ago | parent | prev [-] | ||||||||||||||||
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. | |||||||||||||||||
|