Don't Shoot the "Messengee"
Monday, January 14, 2013
I use open source software almost exclusively, and have done so for years
without anyone complaining about document quality or having to ask me to
re-send something due to incompatibility issues. Nevertheless, I keep an
antenna up for any news that there might be problems of that sort. So it was
that, for a moment, I mistook the title "13 Things People Hate about Your Open
Source Docs" to be about that topic, rather than about common deficiencies in the
documentation for open source software projects.
The
article is quite good, and I wish more OSS developers would read and
heed it, but it also has lessons for anyone in the business of educating others
or promoting a product or idea. For example:
2. Docs Not Available OnlineThe broadly applicable point is in italics.
Although I haven't seen any studies on the topic, I'd bet that 90% of documentation lookups are done with Google and a browser over the Internet. Your project's docs have to be online and available. Given that, it's embarrassing that my own project, ack, would neglect having the docs available where most people would look for them. My assumption was based on my own use case, that if I want to know how a command line tool works, I'll check its man page.
How was this brought to my attention? Users wrote to me asking questions that were answered in the FAQ, which made me annoyed that they weren't reading my FAQ. Turns out they were looking at the website, but I hadn't posted the FAQ there. It's an easy mistake to make. I'm close to the project and I never actually use the FAQ myself, so I don't notice it missing online. Many problems fall into this trap: Authors not putting themselves in the users' shoes. [minor format edits]
The article goes on to extol screenshots and video demonstrations for a similar reason. Likewise, the author cautions against such things as docs being available only online, authors failing to listen to user input, and, most interestingly, "arrogance and hostility towards the user". The last is more common that you might think, and not just among programmers who'd rather be churning out code than having to explain everything to a layman.
Probably the worst possible way to promote something is to default to chalking up ignorance or mistakes to a stupidity or, even more presumptuously, a moral failing on the part of one's audience. As this article clearly shows in multiple ways, the fault can very easily lie with the messenger.
Such a messenger won't get shot, but he'll often find that he won't be heard, either.
-- CAV
2 comments:
‘Many problems fall into this trap: Authors not putting themselves in the users' shoes.’
So you mean the authors aren't actually evil?
Actually, if the author took some time to role-play as a user, it might help then understand.
Seems like the same deal with engineers. I once had a car seat for my son, which had this persistent problem in which the strap I needed to adjust would get stuck between the back seat of my car and the back of the car seat. In order to retrieve it you could just put your hand behind and remove it right? Wrong. The car seat had a bulge (to hold one of the various necessary straps) at the exact place you needed to reach, thereby cutting off your access. Unless your hands were very small the only way to retrieve the strap was to use something long and thin, like pliers. That meant another long journey down to my tool box in the basement. Eventually I wised up and left the pliers in the car but not before placing a few horrible curses on the ancestors of the engineers who designed the car seat.
(Reinstalling the car seat in this case is not an option as it is much more time consuming than simply walking to the basement and back)
Similar theme to what you discussed in Do Designers Do, except in this case it was not that the engineer was asleep or negligent but that he probably never actually used his own device (or it was never tested in the way a parent would actually use it). A day or two of lugging around a toddler would have quickly revealed the problem which could have been fixed by a slight modification to the design.
Steve,
It's probably impossible to know in advance what problems might arise from a new design -- or how easily fixed they might be. (Nevertheless, some still seem too obvious...)
This is why, as you show and the author notes, someone who is not open to reasonable user input is shooting himself in the foot. Thanks for the example.
Gus
Post a Comment