What's with documentation in the OSS world?

I found this post on TSS the other day that talks about JavaServer Faces and the release of a new version of the MyFaces project. More than the announcement itself I noticed in the thread below it a classic symptom of weakness that open source projects suffer from.

For the record I would like to congratulate the MyFaces guys for working hard and providing an implementation of JSR-127 that was elevated to a top level Apache project earlier this year. I remember our first JSR-127 expert group meeting at Sun exactly 4 years ago. JavaServer Faces took forever to materialize and will take a while to become a mainstream web development framework. There are very few worthwhile real-world websites using JSF today but I am sure this will change rapidly with encouraging contributions like Apache’s MyFaces project.

Back to the point I was trying to make in this post. If you read this thread you’ll notice that most of the discussion was not about the cool features provided by MyFaces or the enhancements they came up with since the previous version. It was about lack of documentation! I strongly believe this is a huge impediment to the expansion of open source. Not only documentation but important things like examples, tutorials, online demos, etc. All these things are extremely important and software vendors continue to provide them with every new release. So why can’t the open source community compete in this area? The answer is simple: I don’t know any developer who likes testing, writing documentation, or building examples as much as he or she likes developing cool new features or fixing tricky bugs. And the fact is, the open source community is still largely dominated by developers.

At Orbeon we frequently hear (from our community) that our documentation is far more superior than that offered by similar projects like (Apache Cocoon). The reason is that PresentationServer was a commercial product for a couple of years before we decided to open source it. Our documentation, tutorials and examples are commercial-quality and our users definitely see this as a differentiator.

The conclusion is that open source needs to get some inspiration from the commercial world. It doesn’t matter if an open source project offers great features and fewer bugs if what I am looking for is buried and nowhere to be found. People are just not going to reverse engineer the code to find and use your features. Companies like Orbeon or JBoss offer good documentation with their own products and others like Spikesource provide assistance for LAMP or LAMJ stacks. There is definitely room for what some call Professional Open Source.