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.