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.

Advertisement - Article continues below

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.

Advertisement
Advertisement - Article continues below
Advertisement - Article continues below

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.

Advertisement - Article continues below

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

Staying ahead of the game in the world of data

Create successful marketing campaigns by understanding your customers better

Download now

Remote working 2020: Advantages and challenges

Discover how to overcome remote working challenges

Download now

Keep your data available with snapshot technology

Synology’s solution to your data protection problem

Download now

After the lockdown - reinventing the way your business works

Your guide to ensuring business continuity, no matter the crisis

Download now
Advertisement
Advertisement

Most Popular

How do you build a great customer experience?
Sponsored

How do you build a great customer experience?

20 Jul 2020
Labour Party donors caught up in Blackbaud data breach
data breaches

Labour Party donors caught up in Blackbaud data breach

31 Jul 2020
Why it’s time to expand beyond 16:9 monitors
Advertisement Feature

Why it’s time to expand beyond 16:9 monitors

21 Jul 2020