Okay, so I’ve never used the products that William Shields mentions in his blog post, but the theme still applies. One of the biggest worries about open source is the lack of documentation. I attended a conference last year where one of the attendees asked the speaker about documentation and open source – her concern was that there wasn’t enough documentation for many of the products she wanted to use. Of course I had to follow up after her and say that Koha has amazing documentation (no – I’m not saying that cause I wrote the manual – there are actually a lot of docs that I didn’t write for Koha as well). Anyway, William Shields expresses his frustration with lack of documentation on open source products:

RTFS

This one is predictable. Some will argue that the source code is sufficient documentation. Bollocks to that. While at some point it is inevitable you will end up reading or stepping through the source code of any framework or library you use for any non-trivial purpose, the fact that you have the source code is no substitute for high-level documentation that describes the overall architecture and design principles as well as how to get started and how to do common tasks.

DIY

Another popular defence of poor OSS practices is you can get involved and do it yourself. While theoretically true it is typically completely impractical. For one thing, before you can document something you have to know it. How do you learn it without reading the (non-existent) documentation?

I’m with him on this – it’s bollocks! Not everyone using open source is a programmer – some are just average folks and they need documentation – documentation written in English (or their native language) not programmerese. For that reason, I try to only recommend products that have readable documentation