Documentation for Those Who Don't Read Documentation

© 2000 Lawrence I. Charters

Computers were supposed to lead us to a "paperless society." One wag noted that the opposite is true: a "paperless office" is about as common as a "paperless restroom." People are uncomfortable, if not downright panicked, without paper, in the office or the restroom.

Maybe so, though the paperless revolution does seem to be taking hold in the computer field. An Osborne-1, one of the first portable computers way back in 1980, weighed (at 20 pounds) only slightly more than the paper manuals that came with it. But buy a new Mac or Windows machine and you find almost no paper at all: no manuals beyond maybe a "quick start" guide. On-line documentation is so good, and computers are so easy to use, that paper manuals are unnecessary.

Oh, really?

Palm: A Case Study

The easiest to use computer on the market today is the Palm, by Palm, Inc. Tens of millions of people who've yet to figure out how to keep their VCRs from flashing "12:00" have managed to take these hand-held computers and do useful things with them. The built-in programs may not be as sophisticated as other tools, but people still manage to enter and maintain name and address lists, to set appointments (and alarms) in the calendar, and maintain simple to-do lists. Most of the users have barely glanced at the included documentation.

Of course, the Palm documentation is not exactly easy to comprehend. When you buy any model Palm, you end up with several pieces of paper, some in booklet form and some not. Some of these are advertisements for optional Palm accessories, some of these are for registering your Palm, or for registering for services. There are also "oops" notices, things that should have been included in the documentation but were left out. The documentation itself isn't horrible, but it isn't exactly inviting or easy to use, either.

A couple years ago, Peachpit Press stepped into the gap with one of their famed Visual QuickStart guides: Visual QuickStart Guide: Palm III and PalmPilot. In 252 well illustrated, well-organized and indexed pages, Jeff Carlson told you everything there was to know about the Palm. It must have been successful; Peachpit has recently released a newer book (unseen), also by Jeff Carlson, called Visual QuickStart Guide: Palm Organizers.

What does this mean? It seems to mean that even the easiest to use computer, the Palm, still needs good documentation.

Little Mac Books

Robin Williams essentially invented the "documentation for those who don't read documentation" genre with her original The Little Mac Book, way back in 1990. On the title page of the latest version of this best-seller, The Little Mac Book, 6th Edition, Robin notes that "the book's not so little anymore. Neither is the Mac." Yet this 445 page volume is still the most approachable overview of all things Macintosh, from how the hardware works, to setting personal preferences, to understanding fonts. If you own just one Macintosh book, this should be it. If you own just one computer book, this should be it; then go out and get a Mac to go with it. You'll finally have a computer you can actually understand.

Honest. The table of contents alone is a marvel of clarity, design, and typography, and it only gets better further inside. Aside from, possibly, William Goldman's The Princess Bride, I've probably given away more copies of The Little Mac Book (in multiple editions) than any other title.

And if not The Little Mac Book, then possibly The Little iBook or The Little iMac Book, 2nd Edition. The former (co-written with John Tollett listed as the primary author) is obviously focused on the iBook, and lacks much of the comprehensive detail of The Little Mac Book. On the other hand, it explicitly addresses the many strengths and the few weaknesses of the iBook, paying more attention, for example, to the nuances of mobile computing. Tollett's famed cartoon character, Url Ratz, graces the pages, along with many more practical (if less amusing) illustrations. Url's demonstration of the difference between being at home and being at the office (on p. 13) is a classic.

Similarly, The Little iMac Book centers on Apple's multi-hued iMac, and covers almost everything except which color goes with which style of home décor. This book actually has better coverage of the AirPort than the previous volume, in large part because the former was written before the AirPort technology stabilized. More attention is also paid to application programs, particularly applications bundled with the iMac (AppleWorks, iMovie, Quicken, PageMill, etc.). Both these volumes feature Robin's extraordinary internal design, layout, table of contents and indexing.

All of these volumes are highly recommended.

Visual QuickStart Guide: Mac OS 9

One of the most egregious examples of "no documentation is good documentation" is Mac OS 9. While it may look much like its grandparent, the poorly-documented Mac OS 8, Mac OS 9 is a major upgrade to the Mac's operating system, and yet it comes with almost no paper documentation. The on-line help is excellent, but suffers from two huge limitations: (1) the computer must be in working order for the user to read the documentation; and (2) it is almost impossible to "browse" through the on-line documentation, which essentially requires the user to know what they are looking for before they try to find it.

Maria Langer, a Visual QuickStart veteran, is back with a new book that thoroughly, and clearly, documents Mac OS 9. It is a mixture of the old (how to use KeyCaps, how to resize windows, how to copy files) and the new (how to use Sherlock 2, and a particularly good summary of Mac OS 9 security and multi-user support). As with all Visual QuickStart guides, the book is heavily illustrated, and the topics broken down into small, digestible chunks. Highly recommended for Mac OS 9 users.

Curiously, Langer, Williams and Tollett all live in the dry, desert Southwest, yet write very lively books on usually dry computer topics. Williams moved from California to New Mexico several years ago (Tollett also lives in New Mexico); Langer lives in Arizona. Coincidence? Or clear air?

Mac OS 9: The Missing Manual

David Pogue also noticed the disappearing documentation phenomenon, and talked O'Reilley into publishing his "Missing Manual" series. The first offering is Mac OS 9: The Missing Manual, and the cover drives the message home with the note that this is "The book that should have been in the box."

Pogue has been writing about the Mac for as long as anyone, both as an editor and columnist. His style is somewhat more narrative than the Visual QuickStart guides, but in its own way just as "visual." He also tends to offer a more opinionated view, while still remaining detached and objective. Take, for example, his coverage of the Note Pad:

Steve Jobs may have brought Apple back from the dead when he returned to run the company in 1997, but he's one arbitrary fellow. Among the changes he made upon his return: taking the Note Pad, a favorite [apple] menu item since 1984, out of the [apple] menu.

This banishment to the Apple Extras folder is a shame, because the Note Pad is a handy little storage center for phone numbers, to do lists, Web addresses, brainstorms, and other bits of text you run across in your day-to-day activity. Here's what you can do with the Note Pad:

Pogue then goes on to detail a number of useful Note Pad characteristics. He closes with a highlighted "Tip" that was news to me:

Have you ever wished you could edit or add to a "Read Me" file, but couldn't because the Read Me was, of course, a read-only SimpleText file? […] The solution: Open Note Pad and drag the Read Me icon into the Note Pad window. Now you have normal, editable text in your Note Pad.

If the rest of the "Missing Manual" series is like this first volume, Pogue has a winner: the book is a gem, and highly recommended for Mac OS 9 users. Two more volumes are out (unseen): AppleWorks 6: The Missing Manual and iMovie: The Missing Manual.

HTML User's Interactive Workbook

Macs aren't the only things that are undocumented, or underdocumented. Consider the World Wide Web: the vast majority of Web sites were created by people who had, literally, no idea what they were doing.

Overlook, for the moment, that HTML User's Interactive Workbook is a very good guide to learning HTML, aimed at the complete novice -- the complete novice with a Windows machine. All the internal screen shots are from Windows machines, and the "recommended" HTML software is either Notepad or Wordpad, two very simple text editors bundled with Windows.

On the other hand, Alayna Cohn and John Potter really do assume you are a rank beginner, and skip no steps. If you use the book as intended (doing things in order and not jumping over sections), you will emerge with a far better understanding of the Web and HTML than many Web "professionals," most of whom use Web-layout packages that mask how HTML actually works.

The book is also done with care and wit and, aside from the minor distraction of the Windows screen shots, can be recommended to almost anyone who wants to learn HTML and the Web. For those who already know HTML, however, you won't find anything new. Keep in mind, however, that if you "know" HTML through using GoLive, DreamWeaver, PageMill, or Claris Home Page, you really don't know HTML at all.

Administrating Web Server, Security & Maintenance

Eric Larson and Brian Stephens designed Administrating Web Server, Security & Maintenance as an "interactive workbook" for a course leading to "professional Webmaster certification." The only thing peculiar about the book is the word "administrating" in the title. Though there are some Windows screen shots right at the start, the book does present a solid introduction to the skills, paranoias and details that go into efficiently and safely operating a Web server, regardless of platform.

There are cynics who will say that anything about Web administration appearing in a book must, by definition, be out of date. This overlooks the fact that the principles of Web administration, or more generally of network administration, are well defined. Furthermore, most of the nay-saying cynics don't even know these basic principles, having grown up in an overheated, reactive culture that leaps onto the Next Big Thing before fully understanding the Previous Big Thing. This volume packs in a solid body of knowledge that, with a bit of mental discipline, should take you far beyond where the Web's ambulance chasers will ever go.

Split into two sections, the first part of the book covers Web server administration. Planning your server is covered in detail, as is configuring the server, programming server-side includes, detailing how search engines and Web robots work, and why and how to analyze log files. The second section covers Web security, starting with basic network security and moving to Web server security, CGI security, Web client security risks, online transaction security, and the arcane art of intrusion detection and recovery.

The fill-in-the-blank exercises do get a bit old after a while; it may be suitable for a college workbook, but does anyone like college workbooks? On the other hand, if you've ever struggled to explain to a novice what a MIME type was, or how to read a Web log file, or what IP spoofing is and why it is bad, you'll appreciate both the clarity and the breadth of the book. Highly recommended for Webmasters and wannabe Webmasters.

Building Web Sites with XML

Some books offer good documentation of bad ideas, such as Building Web Sites with XML. It is a well done book, but --

One of the very first sections of Michael Floyd's book is titled "HTML and the Balkanization of the Web." This brief vignette addresses the swift decline of the Web from being a universal Internet communications tool to a mass of warring, incompatible camps formed around proprietary technology. Since the entire book discusses XML from the perspective of Microsoft Windows-proprietary Active Server Pages and Microsoft Windows-proprietary Access database files, this is an ironic introduction to the book. On the other hand, if you'd like to get started in XML (which still hasn't been fully defined) and you also have a Windows NT server running IIS, and have a copy of Microsoft Access handy, the CD-ROM included with the book will have you up and running in no time.

And if you have all of those things, you probably don't spend much time reading this magazine. Which is a pity: the Microsoft Way is not the same as The Right Way. For XML to have a future, it needs to become more generic, and less centered around the great software monopoly.

 Jeff Carlson, Visual QuickStart Guide: Palm III and PalmPilot. Peachpit Press, 1998. x, 252 pp. $15.99. ISBN 0-201-35390-3

Robin Williams, The Little Mac Book, 6th Edition. Peachpit Press, 1999. 445 pp. $19.99. ISBN 0-201-35433-0

John Tollet and Robin Williams, The Little iBook Book. Peachpit Press, 2000. 231 pp. $18.99 ISBN 0-201-70093-X

Robin Williams, The Little iMac Book, 2nd Edition. Peachpit Press, 20000. 311 pp. $17.99. ISBN 0-201-70446-3

Maria Langer, Visual QuickStart Guide: Mac OS 9. Peachpit Press, 2000. xiv, 360 pp. $17.99. ISBN 0-201-70004-2

David Pogue, Mac OS 9: The Missing Manual. O'Reilly, 2000. x, 461 pp. $19.95. ISBN 1-56592-857-1

Alayna Cohn, and John Potter, HTML User's Interactive Workbook. Prentice Hall, 2000. xvi, 348 pp. $39.99. ISBN 0-13-017004-6

Eric Larson and Brian Stephens, Administrating Web Server, Security & Maintenance. Prentice Hall, 2000. xxiv, 567pp. $40.00. ISBN 0-13-022534-7.

Michael Floyd, Building Web Sites with XML. Prentice-Hall, 2000. xxxii, 418 pp. $39.99 (includes CD-ROM). ISBN 0-13-086601-6.