KDE interface for Linux needs better help files

KDE's help reads as though it were written by someone who does not write documentation for a living (or even for a hobby) -- which, of course, is likely to be true.

technofile
Al Fasoldt's reviews and commentaries, continuously available online since 1983

KDE interface for Linux needs better help files

Dec. 11, 1999

By Al Fasoldt
Copyright ©1999, Al Fasoldt

   Most current versions of Linux come with the KDE graphical interface. KDE is the slickest and in some ways most advanced desktop environment for Linux, but it scores a Big Zero in one area: Documentation.
   Figuring out how the KDE desktop is supposed to work can be very frustrating. Figuring out how individual KDE programs are supposed to work can be impossible. I'm making that distinction because refugees from Windows probably have a hard time understanding what KDE really is.
   Let me explain. The K Desktop Environment is not an essential part of the Linux operating system. It's an optional extra; Linux never needs any part of KDE to work. This is also true of the other graphical environments for Linux. KDE provides a desktop and the things that go along with a desktop -- icons, a launch menu, a taskbar, a system tray and so on. KDE also supplies a way for programs to communicate with each other, so that clicking on the icon of a text file within one KDE program might launch a word processor that is itself another KDE program. (In fact, KDE works so well that part of this requirement isn't even necessary; the word processor that automatically opens up the text doesn't have to be a KDE program. And of course we're not just talking about word processors here. There are hundreds of KDE programs of all kinds.)
   KDE's desktop has its own help program (basically, a Web browser that opens up Help pages), but the help it offers is skimpy. Worse yet, it's only half intelligible. And all of it reads as though it were written by someone who does not write documentation for a living (or even for a hobby) -- which, of course, is likely to be true, since KDE is an open-source (in other words, free) program created almost entirely by volunteers. (Contrary to legend, some open-source programmers get paid to write their software, but most do not.)
   Defenders of open source software can't argue that help and documentation aren't important, so we're stuck with an embarrassment for the open source movement: In the case of KDE, at least, documentation and help seem to have been forgotten. It's as if explaining and documenting how software works is of no real importance. This carries an implication that only wimps could possibly care about such thing; real geeks, so it seems, don't read manuals.
   This is nonsense. Help and documentation are possibly more important in KDE than in any other aspect of a Linux PC. For KDE users, the KDE environment IS the computer in many ways. Learning how to use KDE and how to get out of troublesome situations should have a much higher priority among the creators of the KDE system. KDE programs suffer even more than the KDE desktop. I struggled with a utility called kdehotkeys for weeks, trying to create keyboard macros -- keystrokes that would trigger other, more complicated keystrokes -- without the faintest semblance of success. I was trying to write macros by typing the keys I wanted to use, something that seemed to make a lot of sense to me but always failed to work. (The program always threw up a dialog that told me I had entered the keystrokes wrong, and it promptly erased all the ones I had typed in.) I finally found my mistake and was able to use the program normally.
   In the spirit of the GPL -- the GNU Public License -- I'm publishing an article on how to use the program and I'm also sending it to the KDE organization, in hopes it will be incorporated in the next version of khotkeys.
   We're all used to lousy documentation. Windows is full of it. Microsoft made it an art. But the real people out there -- the folks who use computers but are not computer users, if you know what I mean -- won't take Linux seriously if the documentation for its most advanced desktop software is in such bad shape. I can understand why the documentation for what Linux programmers call "unstable" (unfinished and unreliable) programs is sometimes incomplete or missing, but I can find no excuse for blank manual pages, empty help entries and unfinished descriptions for programs that are "stable" (ready to use).
   Good software deserves good documentation. Anything less is unacceptable.