Yeah for Documentation
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 
August 6th, 2009 at 3:44 pm
I work to opensource project. In fact I’m in one of the luckiest ever OSS projects, means that I’m full time paid developer on it. This makes me to value both the power of opensource that brings and also the ability that it brings.
The most important philosophies of free software is to release early and often. If you are a single developer and you work after schedule and you try to contribute your own extension you think that is valuable for this software, you may do firstly implement the feature, test it, QA it, fix found bugs, than document it. Also, if you are a core developer, the biggest feature of yourself is that you are alive and open, meaning that you talk in an open mailing list, you give valuable feedback which value in much time much more than any documentation. At the end, after all bugs are fixed, you will have to balance how much you will stand commenting the code and which parts.
Can you conceive that an contributor will be blocked on documentation. If you think so, you really need to know what need the contributor. If you take a huge codebase, like OpenOffice and try to document it, it will take years of developer time with no user visible value. Probably the audit of code will reveal some small problems or simply they will make a bit faster all the “mess”. But in rest, OSS is the way.
A real life story in our project is this: someone say: I want this feature… and I want to add it. And asks me: what I need to know? And I did review and comment the classes of 5% of codebase and mainly the core of that classes and I’ve made a similar example for him. He was able to contribute a hard to do feature in less than 10 days. For contributing that core classes took me like 2 days of approx. 1% of code. Commenting all, let’s say will take around 2 months. With no value added. In two months I possibly can add 6 times the same hard feature that was initially for the contributor.
It is fairly easy to say: I would like to be this, and is really wanted, but in real life really few products (both commercial and OSS) do have good documentation. And even is done in a very good way, like let’s say MSDN, the resources attached are so big that really few projects can stand to acquire them.