No public Twitter messages.


Open Source Documentation

Aug - 6 - 2009
Nicole C. Engard

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:


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.


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 :)

One Response so far.

  1. I don’t think lack of documentation is primarily an OS problem, it is a general problem in software development to my experience. A while back I wrote tongue-in-cheek piece on it:

ATO2014: Open Source

Charlie Reisinger works for Penn Manor school district and was ...

ATO2014: The first F

Remy DeCausemaker aka "RemyD" was up next to talk to ...

ATO2014: Unmanagemen

Luis Ibanez talked to us next about unleadership and unmanagement ...

ATO2014: Social medi

Rikki Endsley overheard this at a conference: "I don't believe ...

ATO2014: Easing into

Scott Nesbitt was up next with his talk titled: Easing ...