More often than not, documentation is an afterthought, and is what happens when the interesting bits of a software project are over and done.
The coder is not always the best person for the job of documenting a project, if only because, as Richard Stallman once observed, "writing good English is a rare skill among programmers".
Many will tend to ignore the simple instructions that are the starting point for less informed users, and documentation just isn't very interesting to the programmer who has already solved the problems that he or she has set out to solve.
Good code isn't just about solving the immediate problem, but is also about having a solution in place for the next problem that might arise - which requires clear and transparent headers and comments.
A common mantra among programmers is that "good code is 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. In the broadest sense, documentation and the usability of the software are interchangeable notions.
For this reason, Free Software projects are always in need of volunteers to enhance and maintain the wealth of Linux and free software user documentation that is distributed around the net.
Show me the code
In his piece, 'Cathedrals, Bazaars and the Town Council', written back in 1998, Alan Cox took a stab at some of the distractions and failings that surround free software projects, and some of the individuals who involve themselves in discussions around the Linux kernel and other software matters. He called them "the wannabe real programmers" who are "good at having opinions ... catch buzzword disease," or have some speciality they consider the "one true path", the ones who, perhaps inadvertently, divert energies away from getting the job done - and the failure to honour and encourage those who have something else useful to offer.
Among other points, Cox suggested that coders are not the only useful contributors to a project, and that success often depends on others: "I find it sad that many people, when asked to name the most important five Linux kernel people, rarely name some of the most important folk of all - those who maintain websites, change logs, mailing lists and documentation ... Linus says 'Show me the code'. That is a narrow view of a real project. When you hear 'I'd love to help but I can't program', you hear a documenter. When they say 'But English is not my first language' you have a documenter and a translator for another language'."
The willingness of interested volunteers to do the boring jobs, to document and translate the software, to maintain the development trees and mailing lists, and to do the dirty work others don't want to do, has been a vital element in the spread of free and open source software. Undertaken anonymously by thousands of volunteers, this work is ongoing as GNU/Linux and its associated software is translated into a greater range of minority languages around the world.
This kind of effort can not be replicated by commercial software companies who have neither the resources nor the will to reach smaller communities.
Blind trust
Linus Torvalds takes a sceptical stance towards documentation and leaves worrying about this kind of thing to other people. Addressing Andr Hedrick on the kernel mailing list on 12 January 2001, Torvalds, who often makes sweeping verbal gestures with his tongue stuck firmly in his cheek, declared that: "ANYBODY who does driver development without taking the real world into account is a dangerous person. Stacks of papers, diagrams and rules are absolutely worthless if you can't just understand the fact that documentation is nothing more than a guide-line ... Once you realise that documentation should be laughed at, peed upon, put on fire, and just ridiculed in general, THEN, and only then, have you reached the level where you can safely read it and try to use it to actually implement a driver."
