How can the layman get involved with free software?

by Richard Hillesley

Contributing to the documentation of a free software project is a good route for those who want to get involved but don’t know where to start (or how to program), and want to know how it’s done. Richard Hillesley explains…

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.

Follow our to find out about all the latest Linux news, reviews, previews, interviews, features and a whole more.

Dan Saint-Andre

Colleagues, It is very hard to be technical writer for software or software intensive products that are under active development. There is a hugs chasm between “supposed to do” and “actually does” that affects several aspects of the effort to write documentation. The easy parts can be found in “I did XXX, and A,B,C happened.” However, our intrepid writer must now ask several questions:
** was everything thing that happened supposed to happen given XXX?
** Was something missing from the list of happenings given XXX as input?
** Was XXX valid input for each of the things that happened?
** Should there be other input with XXX or instead of XXX to obtain correct results?

I could go on, but this is a comment, not a complete article. Where is our writer supposed to get these answers? Well, the developer’s come to mind as a primary source. Short of human interaction, the developers have design documents, blueprint documents, lists of requirements, detailed test cases, and similar artifacts to the software creation process … don’t they?

In the open source world, the developers use borrowed or stolen time to work on projects that they love often simply for the love if not for associated bragging rights. How motivated are they to spend their time on something other than getting code to work? How often does that code have any sort of written requirements beyond, “Get something working with these rough guidelines…”

Until and unless open source projects include a channel for documentors to pose questions and get answers from the code writers, or until the code creation effort includes at least some writing to describe with is supposed to happen and how it is supposed to happen (if not why, too) then documentation will remain a nice to have but seldom happens.

~~~ 0;-Dan
Professional Technical Writer
Eager to help, but stumped.

jack

An interesting article, but it is a pity that the title is misleading. The article does not answer the question posed. It remains. How would someone who is willing to help documentation efforts go about it?