Successful code isn’t just about stringing bits and bytes together. Code has to be accessible to users and users have to know what the code is doing, and coders are not always the best people to document a project. Documentation isn’t necessarily that interesting to the programmer who has solved the problems he or she set out to solve, and many will tend to bypass the simple instructions that are the starting point for less informed users. Good code may be self-documenting, but, however good a programmer is, code that doesn’t contain some level of internal documentation is hard to follow and maintain, and code that isn’t documented at the user level isn’t always easy to use.
Documentation and the usability of the software can be seen as interchangeable notions and free software projects have always been in need of volunteers to do the less exciting jobs, such as documenting the software or maintaining the websites. The willingness of volunteers to do the apparently less interesting jobs – to document and translate the software, to maintain the development trees and mailing lists, to do the things the coders don’t necessarily want to do – is a vital element in the success of a free software project, and is just as important as the code itself.
The earliest attempt to co-ordinate knowledge of Linux programming efforts was the Linux Documentation Project (LDP), which began life as the Linux FAQ in 1992, and claimed to be the home of one of the first Linux websites on the web (at tdlp.org). The result was a mass of formatted documents that first appeared in hard copy format as The Linux Bible: The GNU Testament, published by Yggdrasil Computing.
Yggdrasil also produced the first plug-and-play Linux, and the first Linux distribution to come on a CD-ROM, but disappeared without trace sometime during the mid-Nineties. Coincidentally, when Yggdrasil filed for a trademark on the title of the book of the project, ‘The Linux Bible’, in May 1996, the claim was rejected on the grounds that the Linux trademark was the sole property of a William R Della Croce Jr of Boston, Massachusetts, who had taken advantage of the rising popularity of Linux to register the trademark. Nobody involved with the Linux kernel project had ever heard his name before. His claims were eventually dismissed, but he was the first of a few to have claimed ownership of Linux, of which the most memorable is The SCO Group.
The LDP meanwhile continues to tick over, and work produced by The Linux Documentation Project still forms the basis of most GNU/Linux system-level documentation and of several books, the best known of which has probably been the Linux Network Administrators’ Guide. Linux and other free software has been fortunate in the extent and quality of online documentation and publications devoted to the software.
The growth of Linux coincided with, and reflected, the development of the world wide web. It also coincided with the rise of US book publisher O’Reilly, which devoted itself in the early days to documenting open source languages and tools, from Perl to Linux device drivers. These days, there are few technical publishers who don’t have at least one or two free and open source texts at the heart of their catalogue – and for the impatient user with an immediate problem or question, the answer is more often than not, a click and a search away. If the internet, properly used, is the most diverse information resource that has ever existed, free and open source software is probably the most heavily documented topic on the net, but close and accurate documentation of what a project intends remains a vital resource for every user.
One of the many advantages of free software is that the source is available to your peers, who will tend to tolerate the good and ditch the bad. Even so, reading the source is not always the best way to discover what the coder intended – which is not always the same as what the code actually does. Good documentation is vital for users, initiates, wannabe real programmers, contributors, and those who just want to get involved, not to mention those who have (or think they have) forgotten more than the rest of us will ever know… and contributing to the documentation (or translation to a minority language) of a free software project is a good way to get involved for those who simply don’t know where to start.