Documentation for Those Who Don't Read
© 2000 Lawrence I. Charters
Washington Apple Pi Journal, reprint
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
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
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]
- 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
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
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 &
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
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
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
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
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
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
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.