Linux

The big Linux Achilles: Documentation

Linux does have one glaring Achilles heel -- documentation. Jack Wallen has a proposed solution for this problem.

Over the last week I have read numerous articles bemoaning the sad state of Linux documentation, and I have to say - I am on board. Linux is an outstanding operating system. There is very little it can not do. The biggest problem (especially for the new user) is getting there.

Man pages are pretty much worthless for new users; the Linux Documentation Project is a failure (I just pulled up an article on "Automounting" dated 2002-12-27, and Google searches bring up mostly forum posts). This, of course, is not to say that developers of applications aren't doing their part. When an application has a help document included, they certainly can be helpful. For instance: the Claws Mail "Manual" entry in the Help menu takes you to the online Claws Mail User Manual - a very useful site.

The included OpenOffice manual is very helpful and massive.

But there are other applications that don't hold up so much. And some applications don't even install the documentation by default. GnuCash is one of them. If you want documentation, you have to install it separately. Sure that's a no-brainer for some of us, but for many, it just fails to compute. And that's where my problem begins.

Linux applications should install with documentation by default. No questions asked. There should not be a point in the installation (of the OS or the application) where it asks you if you want to install relevant documentation. It should just be there. And when a user installs an application with The Ubuntu Software Center (or Synaptic, or apt, or yum, or urpmi), that documentation should automatically be installed. This, of course, is trivial. The real problem is the documentation itself.

I will preface this next section with the statement that there are exceptions. The OpenOffice and GnuCash (when installed) documentation are quite good. However...

As a whole, Linux documentation is poor. The reasons for this are numerous. But I will focus on two of those reasons: Lack of developer support and laziness. Let's address the former.

On numerous occasions, I have offered my assistance to write documentation for a project. But even though this offer is met with open arms, it falls short because the developers become shortsghted with getting their project out into the public as soon as possible. They seem to forget there is not a business model that could crumble if their project is delayed. And releasing a project without documentation is only asking for failure. If a developer is not capable of writing documentation, it is their duty (as much as it is writing efficient code) to make sure the project includes a user manual. Because if this doesn't happen, it only fosters the next problem - laziness.

There is a vicious circle going on with regards to Linux documentation. A developer fails to write proper documentation, forcing users to resort to googling their problems. Thanks to Google, the users (at least those who understand how to "google a problem") are typically sent to forums where others have had the same problem. Thus, through a community-like, drawn-out effort, the problem is (hopefully) solved. Because the users are getting the software working, the absence of documentation is not so much an issue - at least not to the developer. So the developers become lazy.

For this, I have a suggestion that (although it might ruffle some feathers) could solve this issue.

I believe there needs to be some sort of peer review process before an application is accepted into a repository. This process could be simple:

  • Ensure it adheres to the GPL (unless it is placed into the "Commercial" category that might soon hit the Ubuntu Software Center).
  • Ensure the software includes documentation.
  • Ensure the software works as expected.

I understand that what I am suggesting could be one heck of an overwhelming task, but I believe it is one that could mean the difference between vast Linux adoption and moderate Linux adoption. But there is another issue brought about by the fact that Linux itself (not just the applications) needs better documentation. In fact I believe the landscape of the Linux documentation needs to look like this:

  • Linux operating system fundamentals
  • Kernel documentation
  • Sub-system documentation (such as printing and sound)
  • Desktop environment documentation
  • Command-line documentation
  • End-user application documentation

The above list would cover everything. Not all users would need all of the above documentation. In fact the majority of the documentation used would be:

  • End-user
  • Desktop environment

This would be quickly followed by:

  • Sub-system
  • Command line
You might think, upon first glance, that getting people to write the above documentation would be impossible. It's not. Much of it is already written (desktop environment documentation, command line man pages, etc). The big task is organizing it into such a form that is easily accessible to the end user and public in general. This could easily fall under the umbrella of the Linux Documentation Project. I can't think of a better location for the task. However, a governing body should step in to take this task over. The Linux Standards Base comes to mind.
Final thoughts
I might be crazy, but I think this could come to fruition if the right people took it on. The coordination of this effort might be fairly great, at first, but the payoff is well worth it. I have connections with the LSB; I might have to point them to this blog entry and get this ball rolling myself. With the right documentation, Linux' worst Achilles heel could be removed and our favorite operating system accepted en masse.

About

Jack Wallen is an award-winning writer for TechRepublic and Linux.com. He’s an avid promoter of open source and the voice of The Android Expert. For more news about Jack Wallen, visit his website getjackd.net.

32 comments
sar10538
sar10538

you can see how it works!

tarose.trevor
tarose.trevor

...been saying the same thing since i first saw linux years ago... couldnt agree with you more

esetera
esetera

have you looked at FLOSS Manuals? come join us! we are a community of 1500 people writing free docs about free software. its odd you have not heard about us since we collaborate with the fsf, google, mozilla, civicrm, sugar, etc etc etc We have been going now for about 2 years and we have many many excellent docs about free software mostly in English (http://en.flossmanuals.net) but also we have an Finnish community (http://fi.flossmanuals.net) and a Farsi community (http://fa.flossmanuals.net) and also many manuals being translated into various languages (see http://translate.flossmanuals.net/write). for the linux community there is much of interest, but probably most interesting is the excellent introduction to the command line manual which we produced in collaboration with the FSF: http://en.flossmanuals.net/gnulinux You can buy it here: http://shop.fsf.org/ We produce community authored content and we often do this in 2-5 days. For example the following were produced in 5 days : http://en.flossmanuals.net/civicrm http://en.flossmanuals.net/CircumventionTools http://en.flossmanuals.net/Inkscape http://en.flossmanuals.net/opentranslationtools http://en.flossmanuals.net/ardour/ http://en.flossmanuals.net/theoracookbook http://en.flossmanuals.net/sugar and the following were written in 2 days: http://en.flossmanuals.net/gnulinux http://en.flossmanuals.net/GSoCMentoringGuide http://en.flossmanuals.net/firefox We also produce books. All of the above are available in printed form (see bookstore on the right of the front page). We also have produced books in other languages including the recent 'How to Bypass Internet Censorship' book ( http://objavi.flossmanuals.net/books/CircumventionToolsar-translate-2009.12.01-12.02.55.pdf ) which was printed in Arabic for the recent Arabic Bloggers conference (http://advocacy.globalvoicesonline.org/2009/12/05/2nd-arab-bloggers-meeting/) held in Beirut.

misceng
misceng

Windows documentation has failures too often by only dealing with only the most obvious items for which the user will seek help. Too often I go to the manual and it tells me to do all the things I have already tried and then refers me to my support staff which is me. In Linux it is different. For a relative novice there is often no clue as to where to look for help and when found it tells you to take certain actions. These actions are wrapped up in special Linux words about which the newcomer hasn't a clue. For the Linux guru it may be perfectly clear but for others it puts a stop to the take up of Linux.

edhuey.46
edhuey.46

I couldn't agree more. This has done more to hinder the acceptence Unix/Linux based software solutions than any other single issue. I was developing COBOL applications on SCO Unix in the early 80's and found it easier to write my own OS routines than to reverse engineer the available hacks, due to the unblievable absence of documentation. MSoft would be a small niche player if it weren't for this.

alondro
alondro

Linus Face down Is the Best Ops there is you can get any thing answered any time and any where and its simple. Although you engineers need to go back to school, I used to run mainframes bout 30 yrs ago... and engineers were the dimmest...I always had to tell them to turn on there terminal..oh woops plug it in first....

grax
grax

....He did not send a committee!"

kpbarry
kpbarry

One of the main reasons that Ubuntu is my Linux distro of choice is that their wiki-based documentation is always useful to me. There may not be a great central authoritative source for Linux documentation, but I've had much better luck in my experience finding out how to do something non-trivial on Linux than I have with Windows or Solaris. I work with Solaris and Windows servers in my day job. For side projects I use Ubuntu server and I am way more productive because it is so easy to find documentation for server projects. New Linux desktop users might have a hard time with Linux, but I would argue that most novices learn Windows from other users or in school, not from reading documentation.

martin.porter
martin.porter

Good Lord, that sounds like QA. Surely this runs counter to everything that the Linux community stands for?

KimTjik
KimTjik

I could be wrong but my impression is that the quality of documentation is higher among distributions with users who know how to troubleshoot a problem. Some of the mainstream distributions, like Ubuntu and its relatives, have documentation, but it's not on pair with the Wiki effort of Gentoo, Arch, LFS (LFS is more centred around documentation than anything else) and the alike. Mainstream distributions tend to focus on "a quick guide" approach making the gap between users and developers wider. BSD is known for well written instructive man pages. Linux should have the same standard. The problem though is that Linux evolves and changes more rapidly than BSD, which probably makes documentation a challenge. It's no excuse however. As already commented there have been several attempts to address this issue. Since some really good documentation already exist, some distributions already have good Wiki entries, it looks like the need would be to contact and engage the folks working with it, be it on a community or business level, in an attempt to create a backbone of distribution-independent reference documentation. If a backbone exists it also becomes easier for a community to keep their own distribution-specific documentation up-to-date. Hence I agree that it's mainly a question of good coordination. To dig deeper into complex software solutions certain "server-standard" software offers the ultimate documentation themselves. Therefore I doubt this effort has to be wider than the bits and bolts making a typical desktop or basic server work well and be productive. In same cases though it could be good to add documentation describing concepts of how to combine different pieces of software. Still I would say that open-source has the upper hand here. Documentation isn't on the same level as the quality of its software, but it will be much easier and more affordable to maintain such documentation. Troubleshooting proprietary software or even an operating system like Windows, is at times painstaking. A lot of documentation but it's still a guessing game since it's harder to get output explaining the issues, and much documentation is closed as a business strategy in itself. Linux could take advantage of these weaknesses.

CharlieSpencer
CharlieSpencer

I tried the Windows version several months ago. I dropped it after a couple of weeks because I couldn't figure out some of the features. I'm one of those you mentioned who find having a separate installation for the documentation "fails to compute". Forums are useful, but it can be cumbersome looking for previously posted answers to your question. I eventually paid for Quicken. Edited - I agree with Jack that man pages aren't much good to newbies. However, I think there's plenty of third-party documentation regarding the operating system itself. The bookstores are jammed full of content from O'Reilly and the other usual suspects. There are several good free tutorials and guides; the old 'RUTE' is still a good intro. It's in applications where the documentation is usually lacking.

Paul Reitman
Paul Reitman

Whilst I am an enthusiast for the Open Source concept, I am not a techie and I guess I'm getting a bit long in the tooth to learn. Looking back, I became relatively competent with MS windows by just using the OS over a number of years. One of the problems I have experienced is that using Linux (Ubuntu 9.1), if I experiment with the settings to learn something, I am frequently unable to restore the OS to its original state without a great deal of research and often I have to re-install the OS. My point is that for a non-technical person, Linux is not user orientated. Canonical try very hard but they are not there yet. I hope they don't stop trying because I won't stop using their software. It just won't be the main OS.

phregs
phregs

I am very much in agreement with Jack on this one, I feel his prescribed action is definitely something that should be seriously considered. I have been using Linux now (continuously) for approx 3 - 4 years and in that time I have tried at times to move others who are dissatisfied with Windows for whatever reason, over to one form or another of Linux. My efforts fall down on many occasions because of a lack of documentation for those people to refer to. It doesn't matter how many forums or websites you can refer people to, they mostly prefer ONE point of reference where possible. Lets get this moving! ..Phil

AlgotRuneman
AlgotRuneman

The current state of multiple groups doing some of the job is not really bad. It _will_ help if an organization like The Linux Foundation puts some weight behind a coordination of the multiple efforts. It also will be a good idea to engage the major distribution vendors in support of the effort. Canonical and Red Hat certainly have a strong interest in the support features of their products. The guiding group, whoever takes it on, should develop some recommendations expanding on the ones you initiated in this post. Then a documentation community coordinator should make overtures to each of the sites currently trying to write third party documentation as well as trying to get a core of writers (presumably mostly volunteer for smaller projects) ready to step up to the plate to work with the developers. It is clear that this job will be the key to general success. Update: A quick check even identifies a Web site of a "Linux Documentation Project" where the latest newsletter was issued in 2006. So, the idea isn't new. Pulling the job all together under one umbrella...hope it works. It is a good idea.

CharlieSpencer
CharlieSpencer

assuming you're a programmer. Are we limiting the use of open source apps strictly to those who understand the code?

jlwallen
jlwallen

take a look at the book selection on the GNU Press site: Debugging with GDB: The GNU Source-Level Debugger GNU Make Version 3.81 The Bison Manual, v. 1.875 Using GCC: The GNU Compiler Collection Reference Manual, v. 3.3 Those books will surely help a select group of people. But the truth is - those books are not going to help the new user or those who are thinking of migrating to Linux. even on the en.flossmanuals.net site the manuals mostly cover topics new users wouldn't care to learn (with the exception of the Firefox and OpenOfice manuals). What Linux needs is better user-level documentation. But I do applaud what you are doing. Maybe attracting writers to cover user-level topics would greatly benefit the cause?

AlgotRuneman
AlgotRuneman

If much of the documentation effort relates to wiki efforts and may be partially distribution-bound, then probably the documentation project umbrella may have a couple of significant roles to play that will provide the central access people want or need. It seems logical to develop an automated hierarchy index of documentation that would be effectively self maintaining. The core central index would harvest the main documentation links for a distribution where tweaks are put in place that integrate the software into the ecology of the distribution. In turn, the distribution-level index would draw on the appropriate project documentation so that the baseline developer was in the channel. The coordinating body would be charged with the development of specifications for this documentation framework, getting documentation-oriented contributors at each of the sub-levels to give recommendations, and needs. When appropriate, that might include a tagging system that provided a "request for assistance" that would signal the need for documentation writers on a particular project. Those wishing to be documentation writers could then use the central index system to get connected to the team(s) they felt able to support. Where a project had financial resources available from corporate or donation backing a "write for hire" system might even be possible. The central organizing body might also be able to serve as a magnet for contributions. Maybe a branch of WikiMedia could be viable. It wouldn't be suitable as a subset of the Wikipedia itself, but might attract writer/editors who wanted to work without the rules of references or source variety.

Madsmaddad
Madsmaddad

Yes, and I am a bit long in the tooth too. I only revert to MS when I need to use my scanner. Recently repartitioned my computer and thanks to a Linux Wiki document was able to do it and restore all my OS's to working state. I think that there should be one main book for 'basic' linux things that are common to every distro, and something else that spells out the distro specific functions and their use. I note that there is a Techrepublic sheet of common commands. I must download that. I usually find that MS help doesn't. But by phrasing my search correctly I can find the help I need on the forums. I know it would be an impossible task, but I would like to see all the help given on a forum reduced to a Q&A form where the solutions that work are given. This would need a place to state the specific hardware concerned. My grouse over!

ron.carlton
ron.carlton

I too have been using Linux for about 4 years. I have suggested it to many people, some on a tight budget, and have never convinced anyone. They say they need Microsoft Office, I say all they need is OpenOffice, but they are hesitant. And as Jack says, OpenOffice has good documentation. There has to be a lot more paperback books on Linux (Ubuntu!) so that people get the idea that it is a real option. Remember that even the Apple computer doesn't compete very well against Microsoft.

AlgotRuneman
AlgotRuneman

One of the popular GNU/Linux desktops is KDE, and it is also an umbrella for many coordinated programs. As an effort to expand the quality and amount of documentation, the KDE community is sponsoring a series of "Klassrooms" and the most recent is for documentation intended for end users. If you are looking for a place to start improving thing, this might be it. http://forum.kde.org/viewtopic.php?f=4&t=84864&start=0

SMparky
SMparky

My biggest issue with documentation and help forums in the Linux community is the tendency of the writers to assume everyone knows what they know. They'll reference a command but fail to mention it's in the /usr/sbin directory. They'll assume everyone knows how to "compile", or knows what a kernel is. Telling someone to install something is useless if you don't tell them how to install it. Telling someone to mount something doesn't make sense either unless you explain it. (hmm, I just thought of a joke concerning "mounting" a hard drive but I won't repeat it).

sar10538
sar10538

the obvious smiley on this posting but I'm glad you rose to the bait Palmetto. Perhaps you could put your effort into assisting with the writing of documentation or urging developers to document their software than just wasting all your time commenting on these blogs.

The 'G-Man.'
The 'G-Man.'

this relies on people wishing to be documentation writers. If there is one thing we all know about programmers, they hate documentation.

sar10538
sar10538

I pre-date the advent of smilies by just a few years and most people with a degree of wit would see my comment as an obvious jibe at the open source brigade who have been known to quote this in the past. Now, I am one amongst that order but I still know how to write a man page and I worry that we have bread a generation of programmers who see no need to document their work. This is because these projects are largely driven by the programmer and not a true development cycle which would, or should, identify the user support as an integral part of process. A certain degree of up front planning and resource management would certainly turn a sows ear into a silk purse.

NickNielsen
NickNielsen

Others have made pretty much the same post. but were serious about it. You've probably been around long enough to know one or two people like that. That's why we've got the smileys. :D

CharlieSpencer
CharlieSpencer

When I wrote COBOL I often had one line of documentation for every five or six lines of code in the Procedure Division. (Damn, that's the first time I've typed the words 'Procedure Division" in over 15 years.)

snideley59
snideley59

I don't even like commenting my own code (something which has repeatedly bitten me in a nether body region). When I do document a project, I am usually so familiar with it that I skip many critical steps, which makes my documentation useless to the end user, kind of like those man pages that don't even provide a couple of examples at the end.

SMparky
SMparky

Man pages appear to be written by lawyers who oddly seem to devote their time to linux/unix documentation project. They strive to be as confusing to the common man (no pun intended) as possible.

CharlieSpencer
CharlieSpencer

Programming is fun; it's like science class. Documentation isn't; it's like writing a term paper. Some programmers enjoy it so much they'll do it on their own time for free. You won't find too many technical writers volunteering to document open source projects.