Editorial: The State of OSS Documentation

I recognize that Open Source folks are passionate. I understand and I applaud the dedication and fierce loyalty. But for the love of all that is warm and fuzzy, could you please give it a rest? Just for a little while? There is something else that really needs some attention: proper documentation.Editorial Notice: All opinions are those of the author and not necessarily those of osnews.com

I have heard much lately about *Linux_On_The_Desktop*. I read that Linux is finally ready for the desktop. Then I read that Linux is not ready for the desktop yet, but it soon will be. I read that Linux has been ready for the desktop for years. I read that Linux is ready for a few specialized uses, but not ready for the home user. I read that Linux is so easy nowadays that anyone’s grandma can use it. I read that the high level executives in the computer industry themselves can’t cope with setting up their own computers…and then I read about a dachshund in Paducah that managed to install Gentoo unassisted and sent out three emails before his owner caught him.

And always, always, always the discussion comes back to some variation of the following question: “Why aren’t more people using this? Can’t they SEE it is inherently better than MS Windows?”

No. They can’t. And they won’t until a few things change. How can the public at large see anything at all amid this low-hanging cloud of bickering and debate? Suppose an MS Windows end user is considering a switch to Linux, or perhaps just gets curious about trying this newfangled operating system. Where is he supposed to begin? If the experts themselves can’t possibly agree on which one is best for what, how is an innocent newcomer supposed to know what to do?

In order for Open Source software to move out into the mainstream it must first become usable by the mainstream. Is this too difficult to understand? Speaking as a non-programmer end user, a refugee from the tyranny of Microsoft and a reasonably literate person, I am going to tell you something that may shock you. The ugly truth of the matter is….we don’t really care about this stuff.

We have no desire to even know which version of KDE a particular release of a particular flavor of Linux came out with. We don’t know or care which kernel version RedHat uses. We are utterly indifferent as to whether RPM or DEB is a better packaging scheme. The burning question of whether to use XFree86 4.2 or XFree86 4.3 leaves us shrugging. We don’t even care the slightest whit if our computers are using GNU/Linux or GNU/Hurd. In fact, we have no clue about what either one of them really are. The public at large is a hotbed of apathy concerning most of these arguments.

There is one thing however, that we end users do care deeply about. There is an issue that burns in our minds with a searing thirst for knowledge and understanding. There is one question that torments us by day and haunts our sleepless nights. The one question that the public at large cares about is this:

“How in the world am I supposed to make this thing work? Can I have some instructions please? MY KINGDOM for a user manual that I can understand!”

Open Source documentation is terrible. There is no kinder way to put it. Even the commercially distributed software in the Open Source world has substandard documentation. (And believe me, as a technical writer coming from the Windows world, when I tell you that the commercial industrial standards are pretty low). Only a bare handful of Open Source software packages have any documentation at all. And out of the few that do, much of it is either unfinished, inaccurate, or outdated. What counts as explanatory text among geeks would bewilder a nuclear physicist, even a sober one.

Let me pick something at random. I am not trying to make KDE look bad. I personally use KDE almost exclusively, and I love it. But the so-called “help” system….have you looked at that thing? Consider, if you don’t already know what to do, how many people would be able to figure out their solution using just the online help? Really? Just recently I saw someone pointing out how good the documentation for the GIMP is. The GIMP is one of the few packages that can justifiably claim to have user documentation. It is not easy, it is not simple, but it is usable if you keep at it. It assumes, like KDE and most other OSS, a certain minimum level of competence.

This is the key point. Almost all OSS documentation was not written for newbies. It was written by experts for the use of experts. Some of it is surprisingly good. The man pages are a nice example. You open a console, type “man (whatever)” and you get a nice, easy to read explanation. Of course, you must FIRST be aware that man exists, and then you must also be aware that to access the man pages you need to open a console, and then of course you need to be aware of the proper syntax, and naturally you must have a clear idea of exactly what you are looking for and how to spell it….but if you already have gotten that far, the man pages are very helpful.

I have heard all the excuses. Some people claim (with a straight face) that if a program is properly designed it should be self-evident and no documentation should be needed. I have heard the excuse that OSS is still very young, and time is needed to get the documentation up to speed. Problem is, Linux is over ten years old, and some of the other OSS is even older. How long does it take to get started?

Yes, I have seen the Linux Documentation Project. And I ask you, how many newbies know about it? When normal people buy a software package with which they are not familiar, the first thing they do is look inside the package for instructions. When they don’t see anything resembling documentation, how many new customers are going to be clueful enough to think about searching the net for something called Linux Documentation Project? And even if they stumble over it, how are they supposed to know what to search for?

Not every newcomer to the fold is going to be blessed with a wise and patient sensei to guide their first faltering footsteps along the Way Of The Penguin.

Truth is, most geeks hate to write. They are not good at it, and they know this, and they would rather spend a week in lockdown with 5 large cell mates than write user documentation.

I come before you to plead. I speak for the unwashed masses of non-technical end users who would dearly love to try using OSS, but have no idea HOW. I speak for the clerical staff that keeps getting their work eaten by MS Word. I speak for the accountant that has seen Peachtree lock up their system once too often. I speak for the hapless sales representative whose server just crashed, leaving him stranded 500 miles from headquarters with no way to close the sale. For all of us, I beg.

Can you stop bickering among yourselves long enough to tell us how to run this stuff? In terms we can understand? Please?

Tell you what. I will send you money. Write some usable documentation that lets me buy OSS and get productive with it, but does not require me to become a geek-in-training, and I will send you money. Lots of money. I will BUY your product. How’s that? Could you get a better offer anywhere?


  1. 2003-11-19 9:25 pm
  2. 2003-11-19 9:33 pm
  3. 2003-11-19 9:44 pm
  4. 2003-11-19 9:44 pm
  5. 2003-11-19 9:44 pm
  6. 2003-11-19 9:48 pm
  7. 2003-11-19 9:48 pm
  8. 2003-11-19 9:49 pm
  9. 2003-11-19 9:52 pm
  10. 2003-11-19 9:53 pm
  11. 2003-11-19 9:56 pm
  12. 2003-11-19 10:02 pm
  13. 2003-11-19 10:06 pm
  14. 2003-11-19 10:11 pm
  15. 2003-11-19 10:13 pm
  16. 2003-11-19 10:17 pm
  17. 2003-11-19 10:22 pm
  18. 2003-11-19 10:23 pm
  19. 2003-11-19 10:23 pm
  20. 2003-11-19 10:24 pm
  21. 2003-11-19 10:27 pm
  22. 2003-11-19 10:28 pm
  23. 2003-11-19 10:37 pm
  24. 2003-11-19 10:39 pm
  25. 2003-11-19 10:40 pm
  26. 2003-11-19 10:42 pm
  27. 2003-11-19 10:49 pm
  28. 2003-11-19 10:58 pm
  29. 2003-11-19 10:59 pm
  30. 2003-11-19 11:00 pm
  31. 2003-11-19 11:00 pm
  32. 2003-11-19 11:04 pm
  33. 2003-11-19 11:06 pm
  34. 2003-11-19 11:07 pm
  35. 2003-11-19 11:08 pm
  36. 2003-11-19 11:13 pm
  37. 2003-11-19 11:13 pm
  38. 2003-11-19 11:16 pm
  39. 2003-11-19 11:21 pm
  40. 2003-11-19 11:22 pm
  41. 2003-11-19 11:32 pm
  42. 2003-11-19 11:33 pm
  43. 2003-11-19 11:39 pm
  44. 2003-11-19 11:45 pm
  45. 2003-11-19 11:51 pm
  46. 2003-11-19 11:54 pm
  47. 2003-11-20 12:00 am
  48. 2003-11-20 12:01 am
  49. 2003-11-20 12:13 am
  50. 2003-11-20 12:20 am
  51. 2003-11-20 12:22 am
  52. 2003-11-20 12:32 am
  53. 2003-11-20 12:38 am
  54. 2003-11-20 12:40 am
  55. 2003-11-20 12:44 am
  56. 2003-11-20 1:01 am
  57. 2003-11-20 1:03 am
  58. 2003-11-20 1:09 am
  59. 2003-11-20 1:14 am
  60. 2003-11-20 1:48 am
  61. 2003-11-20 1:53 am
  62. 2003-11-20 1:53 am
  63. 2003-11-20 1:57 am
  64. 2003-11-20 2:03 am
  65. 2003-11-20 2:04 am
  66. 2003-11-20 2:13 am
  67. 2003-11-20 2:22 am
  68. 2003-11-20 2:23 am
  69. 2003-11-20 2:27 am
  70. 2003-11-20 2:33 am
  71. 2003-11-20 2:36 am
  72. 2003-11-20 2:41 am
  73. 2003-11-20 2:41 am
  74. 2003-11-20 2:44 am
  75. 2003-11-20 2:57 am
  76. 2003-11-20 3:04 am
  77. 2003-11-20 3:18 am
  78. 2003-11-20 3:29 am
  79. 2003-11-20 3:30 am
  80. 2003-11-20 3:36 am
  81. 2003-11-20 3:38 am
  82. 2003-11-20 3:41 am
  83. 2003-11-20 3:58 am
  84. 2003-11-20 4:00 am
  85. 2003-11-20 4:22 am
  86. 2003-11-20 4:22 am
  87. 2003-11-20 5:05 am
  88. 2003-11-20 5:07 am
  89. 2003-11-20 5:09 am
  90. 2003-11-20 5:30 am
  91. 2003-11-20 5:44 am
  92. 2003-11-20 5:52 am
  93. 2003-11-20 9:10 am
  94. 2003-11-20 9:30 am
  95. 2003-11-20 10:12 am
  96. 2003-11-20 11:09 am
  97. 2003-11-20 11:57 am
  98. 2003-11-20 1:30 pm
  99. 2003-11-20 1:45 pm
  100. 2003-11-20 2:09 pm