RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Is Documentation Holding Open Source Back?

Doing a better job at documentation can turn technical excellence into universal acceptance.

pen source software has been extremely successful at the technology level. Apache, Mozilla, Linux, Perl, Python—the list of stable and robust open source software is impressive and growing. So why is open source still considered fringe?

Let's start with the poor discoverability of open source tools. How do you find the right tool for the job? More importantly, if you stumbled across the right tool would you be able to recognize it based on the information on the Web site? Take a random project on Sourceforge: Is it easy to recognize what the project does? Where it is going? What problem it was meant to solve?

These are the introductory questions that engineers ask when they first look at a project. Unfortunately, quality introductory documentation is what most open source projects lack. The API and user documentation that most projects have is largely ignored until engineers start using the tool.

The State of Open Source Introductory Documentation
I wanted to do an unscientific study, a survey, of the quality of introductory documentation for open source projects. To do this I took the top 20 entries in the 'Development tools' category of Sourceforge and analyzed their Web sites. The ground rules were fairly simple: The documentation should be located on the central site and should be able to be reached in no fewer than five clicks from the home page. These rules had little impact on my testing. I found that if documentation was available, it was centrally located and easy to find.

The focus of my analysis was introductory documentation. This is the type of documentation that you read before you start using the tool, including the introductory text on the home page of the site, the FAQ, and use scenarios or case studies. The survey did not include user's guides or API documentation.

Having used the top 20 projects, as opposed to a random sampling, you would expect my research to favor more heavily documented projects. This is borne out by the fact that all of the projects sampled were documented to some degree. However, after assessing the quality of the introductory documentation it was clear that there is a lot of room for improvement.

All of the sites had some brief description of what function the tool performed. Only one in every 10 projects had a clear and concise statement of what problem the tool was meant to solve. Almost all provided a statement of the function of the tool, but only one of the 20 projects I looked at used any graphics to describe the function.

Only half of the projects had FAQs. Of those less than half again answered the simple question of what the tool was meant to do. Is the FAQ only intended for engineers already using the tool?

Half of the projects had some type of tutorial or sample code. Of those only a third had documentation that provided scenarios for when the tool was useful and in what configuration. Information about the hardware or system requirements for the software was given by only 15 percent of the projects.

Twenty percent of the sites used esoteric jargon or acronyms without definitions. This is assuming a great deal from the reader. Can we really assume that every reader can understand JXTA from the acronym alone?

The vast majority of the project sites used the front page to show the change log of the tool. Certainly this provides benefit to the engineer who is already using the tool, but it provides no benefit at all to someone interested in an introduction to the tool.

Will Documentation Help?
It's one thing to prove that the documentation we currently have is poor; it would be much better to also prove that documentation would significantly improve adoption rates. Unfortunately, I have no direct data to support that. However, there are certain trends that clearly indicate, at least to me, that better documentation directly improves adoption rates.

Technology adoption is a well-understood trend. It starts with early adopters who tolerate the bugs and the bad interface to get access to leading edge tools. To move from early adopters to ubiquitous use involves making the tool easy to use and providing comprehensive and accurate documentation. It also involves communicating the benefits experienced by the early adopters to the potential users. This is the introductory information that is frequently lacking in open source projects.

We can also look at the world of commercial software. Software marketing professionals don't start with what the tool does. They start with customer empathy by assuring the consumer that the vendor understands their problems. Then they show how their product provides an appropriate solution. "Here is your number one problem; this is how we fix it." It's a simple and effective approach and it's not patented. Anyone can use it.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date