If open-source products are to ever challenge well-established commercial offerings, the documentation provided by them must improve greatly.

During the past few weeks, I have been evaluating two open-source Enterprise Service Bus (ESB) projects: Mule and ServiceMix, for use in an application I am currently working on. My initial glance of their respective websites led me to believe that both of these projects had a vast amount of documentation that would allow me to quickly learn how to use their products and be productive with them in a short period of time.

My initial optimism quickly turned to dismay as I examined the content of their respective websites, wikis and mailing lists in-depth and discovered that while their websites contained a lot of data, the ‘data’ was not organized in a coherent manner nor was it comprehensive enough to be considered useful 'information'. In fact, I got the distinct impression that the developers of these projects felt that perusing the source code of their respective projects was the expected way to go about understanding how to use their software.

The problem with this point-of-view is that reverse-engineering source code generally takes more time than reading quality documentation, which translates into wasted time and effort on the part of the developer trying to use the product and an increased cost to the customer.

Two of the oft-mentioned advantages of open-source software are that it is free and the source code is available for individuals to review and modify if necessary. If I have to spend more time becoming productive with an open-source product verses a commercial offering, it can hardly be called ‘free’ anymore. As for being able to examine the source code, that should be the exception; I want access to the source code to ensure it is secure or to add needed capabilities but I do not expect to have to read it to learn how to use the product itself.

It is interesting to note that the most successful open-source applications all have quality documentation in the form of documentation located on their respective websites and/or published books that describe in detail how to install, configure and utilize these products.

Popular examples include:

• Linux
• PHP
• gcc
• MySQL
• Apache

Java-related examples include:

• JBoss
• Tomcat
• Spring
• Hibernate
• Eclipse
• JasperReports 

Why then, do so many open-source projects fail to provide quality documentation? I suspect there are many reasons but here are two possible answers:

1. Many open-source developers are 'hard-core' developers whose gratification comes from others admiring their source code for its elegant design, its clever coding techniques, etc., rather than for what their source code can be used to accomplish. Documentation to them is not 'fun' or 'challenging'.
2. Other open-source developers see the potential to make money from their efforts by providing documentation at a cost and/or providing 'services' (consulting, training, etc.) around their open-source project. Actually, I have no problem with this at all; open-source does not imply ‘free’. If a developer puts his or her time and effort into developing a quality product, then I believe they deserve to be compensated in some form. JasperReports is an example of a quality open-source project that provides comprehensive documentation at a very reasonable cost.

Getting back to Mule and ServiceMix, my message to the developers of these two projects is that professional software development companies will not utilize your products (or open-source software in general) unless quality documentation is available. It is not the elegance or cleverness of your source code that we appreciate; it is the ability to meet our customer’s requirements using your products in a time and cost-effective manner.

It is my sincere hope that both of these projects work hard to improve the state of their documentation because both of these projects have the potential to be outstanding frameworks for building quality enterprise solutions.