The Catch-22 Of Opensource Documenation

Opensource projects tend to have a well-earned reputation for being poorly documented. Originally this was caused by the fact that most of the people who knew the codebase were developers who didn’t have the skills or interest in writing the documentation. With opensource becoming more mainstream and more people getting involved I think that reason, while still having an effect, has become less of a problem. Despite that the quality of opensource documentation hasn’t improved – if anything it seems to be getting worse. More and more projects don’t even have half-decent reference information and just a few scraps of information on where to start.

It seems that documentation is now the way that people get paid for opensource. More and more projects are recommending one or more books instead of providing documentation for free. Perhaps having a paid form of documentation improves the quality but it doesn’t matter much. There’s simply not enough free documentation available to let you decide if the project actually does what you want and will meet your needs.

Not everyone who writes books about opensource is “holding out”, a number of them are contributing documentation improvements back to the project, but the give away the code, sell the documentation is a disturbing trend that limits the benefits of opensource. We need to start realizing that the documentation is just as important as the code itself – if we insist on the code being free, we should expect the same of the documentation.