The need to know: Documentation in Linux

Documenting the development of open source software is key to keeping it easy to use, but some disagree on its necessity.

Torvalds concluded with the scathing dismissal: "I'm continually amazed and absolutely scared silly by your blind trust in paperwork, whether it be standards or committees or vendor documentation."

The need to know

Users are not so privileged, and have a need to know. Documentation is a vital component of the users' experience of any system.

The Linux Documentation Project (LDP), which emerged concurrently with the World Wide Web and predated knowledge of the web, began life as the Linux FAQ in 1992, and claimed to be the home of the first (of many thousand) Linux websites on the web (at tdlp.org). Like many of the early features that were developed for the GNU/Linux operating system, many of the early documentation efforts were undertaken to "scratch an itch" by programmers and users who needed to know how to get things working, what worked and what didn't work.

The result has been a mass of formatted documents that first appeared in hard copy format as The Linux Bible: The GNU testament, published by Yggdrasil Computing way back when.

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. Coincidently, 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 unexpected 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 nascent popularity of Linux to register the trademark, and of whom nobody involved with the Linux kernel project had ever heard.

The claims of Della Croce were eventually dismissed, but he was just the first of many to have claimed ownership of Linux.

Every time I learn something new...

In the beginning, when Linux and free software could still be considered the preserve of hackers, academics and hobbyists, documentation tended to be ad- hoc, an afterthought, something to be dealt with later. But times have changed. User-oriented projects, such as KDE, OpenOffice or GNOME, tend to the view

that documentation and usability issues are as vital to the success of the project as the code.

These days, the LDP appears to be relatively inactive, but work produced by The Linux Documentation Project and GNU still form the basis of most of the system level documentation available with every distribution of Linux, supplemented by work produced by the Linux commercial distributions and other interested parties.

Documentation and usability issues are seen as key to the development of the Linux desktop. GNOME and OpenOffice usability research, for instance, is sponsored by Sun Microsystems.

Commercial open source projects, such as JBoss, are, of necessity, self documenting. Ubuntu sponsors a wiki to answer user questions and provide supplementary documentation, and there are countless websites, discussion groups and mailing lists dedicated to the specialist concerns of users.

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.

The visibility of the source code is an essential element of Linux and free software, but 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 programmers, contributors, and those that 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 - for, as the philosopher of Springfield, Homer Simpson, once said:

"Every time I learn something new it pushes some old stuff out of my brain."

Featured Resources

The ultimate law enforcement agency guide to going mobile

Best practices for implementing a mobile device program

Free download

The business value of Red Hat OpenShift

Platform cost savings, ROI, and the challenges and opportunities of Red Hat OpenShift

Free download

Managing security and risk across the IT supply chain: A practical approach

Best practices for IT supply chain security

Free download

Digital remote monitoring and dispatch services’ impact on edge computing and data centres

Seven trends redefining remote monitoring and field service dispatch service requirements

Free download

Most Popular

Best Linux distros 2021
operating systems

Best Linux distros 2021

11 Oct 2021
HPE wins networking contract with Birmingham 2022 Commonwealth Games
Network & Internet

HPE wins networking contract with Birmingham 2022 Commonwealth Games

15 Oct 2021
Veritas Backup Exec 21.3 review: Covers every angle
backup software

Veritas Backup Exec 21.3 review: Covers every angle

14 Oct 2021