Documentation?

As we zero in on the second “production” release of the Linux kernel, 1.2, the most common complaint I hear about Linux is its lack of documentation. But, is that really a problem? I think not. Here's why.

What this means is that if you are looking for a book on basic Linux commands or how to use the VI editor you have a lot of choices. When you go shopping you just have to say Linux every time you see Unix. Sure, there are some differences, but not many from the user's point of view. As all “Unix-like” systems converge on the various standards, such as POSIX and Spec 1170, the differences disappear. Today there are more differences between a BSD-based version of Unix and a System V-based version of Unix than there are between either of these and Linux.

There is real Linux-specific documentation. The Linux Documentation Project (LDP), headed by Matt Welsh, is producing high-quality documentation. Right now, Matt's own Linux Installation and Getting Started is either included with most CD-ROM distributions or available from the distributor or reseller.

Olaf Kirch's Linux Network Administrator's Guide has been published by SSC and an O'Reilly version is also on the way. The excellent coverage of networking in general will probably make this book the first Linux-specific book to become commonly used by non-Linux (read that as Unix) users as well.

Michael K. Johnson, our editor, is now in the process of updating his Linux Kernel Hacker's Guide (KHG). You will see some of this information in his new monthly Kernel Korner column. And, once it is up to date, SSC plans to publish it.

There are more LDP books on the way. Expect to see a System Administrator's Guide, Programmer's Guide, User's Guide and man pages. And, of course, all of these books are available on the archive CD-ROMs and ftp sites.

Besides the LDP efforts, publishers are getting on the Linux bandwagon. Springer-Verlag has published a book titled Linux: Unleashing the Workstation in Your PC, available in both German and English. O'Reilly is working on a Linux book, and rumors indicate that Benjamin-Cummings and SAMS are working on Linux books. 1995 will probably be the year of Linux documentation.

Many people who are complaining just downloaded Linux off an ftp site or bought an archive CD. In either case, there is lots of documentation available but it doesn't print itself. You need to remember that if you bought SCO Unix you probably dug into your pocket for $1,000 or more as opposed to less than $100 for Linux. Either take some money and buy the books you need or take some time and print out what is on the CD.

The other problem, of course, is getting you to read the documentation. Many CD vendors are now including a small book with the distribution to get you started. People seem less intimidated by a 20-page insert in the CD case than by a 1,000-page manual. Just remember, you may still need that 1,000 pages of documentation to find all the answers.

Yes, there is. Linux is changing so rapidly that it is hard for the documentation to keep up. For example, if you buy a printed copy of the Linux HOWTOs that has been sitting on a bookstore shelf for a few months, most of it is already out of date. Documentation that will be outdated by the time it is printed is not what publishers (or booksellers) like.

But this is one of the reasons the LDP separated the HOWTOs from the LDP books. These books evolved with much feedback from the early users and, as each one becomes stable, they are becoming available in printed form.

Many of the distributors include HOWTOs on their distribution CDs along with browser tools to search, read and print them. The initial focus has been browsers under MS-Windows. (As much as I dislike this dependence on Microsoft, some people are going to need to be able to read the documentation in order to get Linux up and running.)

Matt Welsh, coordinator of the LDP, has recently made the HOWTOs available on sunsite.unc.edu in HTML format (as well as other formats). This means that if you have the HTML format documents in an uncompressed form on your system (some archive CDs have this) you can use a WWW browser such as Lynx or Mosaic to access these documents in hypertext form. And, as the lead time on pressing and distributing a CD is shorter than that for a printed book, the consumer can get the best of both worlds—stable documentation for their bookshelf and up-to-the-minute documentation on the CD.

In conclusion, the Linux community and the publishing community have heard you and are taking action. There is documentation and there will be more. But remember your obligation: support these publishing efforts including the LDP, get the documentation and, last but not least, RTFM.