A recent post in
eWeek about open source projects and the importance of documentation:
"This may be stating the obvious, but not all open source and "shared source" development projects are created equal. Even when you're dealing with a "professional" open or shared source project, where you're paying for support, what you get out of that investment depends on how well the core of the project is run. And the best indicator of how organized a project is, as far as I'm concerned, is how good the documentation of the code is.
JBoss is an example of a well-documented project. Sure, we can argue over the "purity" of JBoss' LGPL license and whether it's really "open source" or not all day long--but the documentation is excellent. OpenNMS, the open network management system, also boasts some decent user and developer documentation.
There's a couple of reasons why these projects have such good docs. For one, they are supported by professional developers. But they're also inherently team projects -- no single developer has coded the majority of the project, so documentation is key to keeping the project rolling and growing.
Then there are the unlit hallways of a poorly-documented project, where you spend weeks bumping into walls trying to find where everything is. I'm stuck dealing with a couple of project like that right now, and it's a special kind of hell.
To paraphrase Leo Tolstoy, "All well-documented open source projects are alike; each poorly-documented project is poorly documented in its own way." Sometimes it's because of neglect, and sometimes there's an ulterior motive. Is it because the team thinks it can make more money off support and consulting if the docs keep others from building on top of their work? Or is it because there's really one guy doing all the coding, and he doesn't think he needs documentation?
If you run across a project that is using its lack of documentation as a bootstrap business model, steer clear. "Open" projects that rely on the obscurity of the code to create revenue for the support team aren't really open, and will probably never grow, because whatever community they try to create won't be able to contribute anything useful back to the project. And you don't get too many "enterprise license" customers if all you're giving with that license is a phone number and some installation help."
