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.