When I was in Elementary school (or rather, the UK’s equivalent thereof), the other children would try to spell my name. “J – O – N” they wrote.
“No,” I would explain. With an “h”.
“J – H – O – N”
Argh.
It’s Not Always Obvious
What was obvious to me – that the “H” went after the “O” – was not so obvious to the other children in my class. It always frustrated me that they just didn’t get what I meant, but in fairness the information I gave them was sufficiently ambiguous that I can hardly blame them for coming to the wrong conclusion. I should have given more explicit instructions about where to place the “H”.
Incidentally Speaking
Anybody who has ever worked on a Helpdesk, supported software, or dealt with network incidents has undoubtedly been on the receiving (and quite possible the delivering) end of the same problem. Outage and bug reports are inevitably short on facts and lacking in accuracy, which makes investigating and diagnosing problems far more time consuming that it really should be. And the worst culprits? Quite often people who should know better – us!
How to Report Bugs Effectively
Simon Tatham, author of PuTTY, published a document in 1999 that is still referenced today (with this post cunningly proving the point) called How to Report Bugs Effectively. The document has a lot of great advice which we should all read, but the one thing that sticks in my mind more than any other is this:
“Be careful of pronouns. Don’t use words like “it”, or references like “the window”, when it’s unclear what they mean. Consider this: “I started FooApp. It put up a warning window. I tried to close it and it crashed.” It isn’t clear what the user tried to close. Did they try to close the warning window, or the whole of FooApp? It makes a difference. Instead, you could say “I started FooApp, which put up a warning window. I tried to close the warning window, and FooApp crashed.” This is longer and more repetitive, but also clearer and less easy to misunderstand.”
In English we use “it” more often than is probably healthy, perhaps because it keeps our sentences from sounding like stereo instructions, but in a technical environment that’s a really dangerous thing to do. If you have not read Simon’s guide before, I strongly recommend it as required reading for everybody on the Engineering teams. And then once those people are up to speed, you can publish it (what? Yes, the document…) on your intranet, right next to the Helpdesk link!
With My Own Eyes
I have a rule when troubleshooting which seems pertinent to this discussion Roughly put it’s this:
I don’t want to hear your interpretation of things; show me the raw data so I can make my own assessment.
I have lost count in the past of the number of times somebody has dismissed a traceroute as being “fine” and thus not worthy of further investigation, when in fact had I seen it, it would have been clear that the path taken was not the right one, and might explain why we’re having a problem. Perhaps you’ve been told that somebody is seeing “ping loss”, but unless you see it, how would you know that the actual pattern was “!.!.!.!.!.!.!” – which to many of us indicates a very specific issue. That’s the problem when somebody else obscures the detail from you and just delivers the headline. I like – I need to see those results for myself. I don’t mean to offend the person who gathered the information and provided their own analysis – and there’s a good chance I’ll agree with them anyway – but I’ve been misled too many times in the past to trust anybody else to summarize results for me, which makes me a bit of a pain when I’m on a troubleshooting call!
Documentation Failure
Deep down, I’ve wondered whether our innate lack of accuracy is what makes some people so resistant to creating documentation? You’ll know if you’ve ever tried to write detailed technical documentation that the process is extremely challenging. If it’s not, then either you’re one of the very rare people who naturally write amazing documentation or, more likely (let’s be honest), you’re one of the people who is unaware how ambiguously they communicate. In fact, often the best way to do a technical document review is to give it to somebody who is not an expert in that area and see if it makes sense. Trying for the first time to follow the logic of a technical explanation is a very revealing experience.
Let’s All Do Better
Together we can cure the bad communication problems that are rife in technical environments. If we begin, as engineers, by improving our own communication accuracy, we’ll then be in a much better position to help educate our users so that they can provide us better trouble reports. And wouldn’t that be nice?
Good luck!
Jhon.
Leave a Reply