I perceive an enormous difference in the amount and quality of the documentation in a number of Open Source projects, some of which is quite excellent. Some examples serve to illustrate my point.

As very good, I'd categorize PHP's phenomenal manual which exists in several languages and in a number of different formats. Some other excellent examples include Exim's online specification which is also available as PDF, both of which clearly show changes between one release and the next. The Apache web server is also well documented in a number of manuals and howtos. Smaller packages such as fetchmail and nail are also well documented.

Unfortunately, the OpenLDAP LDAP directory server lacks in documentation. There is a lot of information in the admin guide and in the FAQ-O-Matic and the manual pages of course, but a lot of useful information can only be pieced together from the mailing lists. What is missing is a comprehensive all in one book sort of guide.

In the category quite awful I'd put the otherwise very good Dovecot IMAP server. Its documents are haphazardly spread across a documentation wiki and a mailing list.

I've used these examples simply to bring my point home. There are hundreds or thousands of other projects which also do excellent work. I confess that to me, quality of code is of course more important than that of the documentation (after all, I can read the source, Luke), I do believe that good software should encompass good documentation.

Oh, and I do of course realize that I shouldn't complain but instead contribute to projects' documentation.


blog comments powered by Disqus