One of the canards about Free and Open Source Software that is peddled by the unscrupulous marketers of proprietary software is that their product is superior because, among other things, the scruffy, sandal-wearing Communists that write and distribute their software for free do not bother to adequately document that software; thereby placing in jeopardy the business processes in the enterprise that rely on said software to continue to profitably grease the wheels of the juggernaut of Capitalism.

At heart, it really is an attempt to paint FOSS as a hobbyist’s pursuit, unworthy of consideration by Fortune 500 CIOs as it is not in the same league as “professional,” proprietary product. This FUD is not restricted to the usual suspects; it has also been raised by other, presumably more objective commentators:

Open Source documentation is terrible. There is no kinder way to put it. Even the commercially distributed software in the Open Source world has substandard documentation. (And believe me, as a technical writer coming from the Windows world, when I tell you that the commercial industrial standards are pretty low). Only a bare handful of Open Source software packages have any documentation at all. And out of the few that do, much of it is either unfinished, inaccurate, or outdated. What counts as explanatory text among geeks would bewilder a nuclear physicist, even a sober one.

A more recent survey, published in 2010, identifed the same issue for businesses, in slightly less histrionic language:

The No. 1 reason for not choosing open-source solutions was lack of support followed by poor documentation.

My experience of FOSS documentation, particularly over the last twelve months, has been just the opposite.

From the middle of 2012 on, I made a couple of significant changes in my computing environment; I moved from SysVinit to systemd, garden variety to UEFI booting and changed my shell from Bash to Zsh. In each of these cases I found myself having to turn to the documentation the community has provided in order to understand the implications of the change, and to familiarise myself with the new tool or approach.

I posted at the time about moving to systemd, and I don’t think—in retrospect—I credited Lennart Poettering enough for the series of posts he wrote detailing the design decisions and implementation of that system; those posts (at the time 12, now grown to 20) are an impressively thorough, and thoughtful, document of the new init system.

Similarly, when I started reading about UEFI booting, I quickly found myself at Rod Smith’s site. Rod has compiled an exhaustive and authoritative resource on GPT, EFI Stub loading and UEFI booting in general. Reading through his clear, approachable documentation made transitioning to UEFI a much simpler process than, given the inherent complexity in the ecosystem, I would have thought possible.

Then there is Zsh.

Because zsh contains many features, the zsh manual has been split into a number of sections…

And goes it on to list those seventeen sections. If you are not a fan of man pages¹, there is the Zsh Documentation, the User’s Guide and wiki. This amounts to a literally staggering amount of information—it is no wonder that preconfigured zsh systems like grml are so popular; they provide relatively simple ingress to the byzantine ways of this powerful shell.

Finally, also last year, I was privileged to chair the judging for the 2012 New Zealand Open Source Awards. This exposed me to the amazing contribution Michael Kerrisk has made to GNU/Linux over the last decade. He is the author, or co-author, of over 300 man pages; and these aren’t the glamorous, application pages read by the masses, but the system pages that document the kernel and glibc APIs.

All of this suggests to me that the state of documentation for FOSS is anything but parlous. At every turn over the last year, when I needed to be able to refer to documentation for a project, there was a surfeit of it. And I have only touched on what would normally constitute the primary sources; there is also all of the other community-driven documentation around projects, like the Arch Wiki or the Stack Exchange sites, the support available on forums, IRC, blog posts, etc.

Compared to the sterile, mostly out-of-date (and expensive) documentation that accompanies proprietary software, FOSS is an Alexandrine utopia…

Notes

1. And, god knows, I am; man pages are a constant source of knowledge and delight (and pretty much the only way I can contribute to projects that I am indebted to).

Creative Commons image of documents by Marcin Wichary on Flickr.