Where are the instructions

©2002 Lawrence I. Charters

SNAC Time No. 281, January 2003, pp. 6-7.

We begin with a little history.

Once upon a time, when you bought a computer, the computer came with documentation. Buying an IBM mainframe? Better install a library, complete with paid librarian. Buying an Osborne-1, the first true mass-market portable? The documentation weighed almost as much as the computer, and the computer weighed 20 pounds.

But as personal computers have become more powerful and more complex (and, oddly, more inexpensive), the documentation has become scarcer. A brand-new dual processor Power Mac G4 comes with a printed guide that explains how to set up the machine and add memory and hard drives (tasks which are rarely performed), but has only a small, colorful, almost wordless booklet on Mac OS X. Since the user will spend far more time using Mac OS X than installing hard drives, what happened to the documentation?

There are two answers: first, Apple (and virtually every other manufacturer) discovered that most users don’t read the documentation. Either they will stumble along in ignorance, guessing at how things work, or they will ask their local guru how to do things. The brighter ones will congregate in user groups and share their discoveries, including the discovery that nobody else read the documentation, either. (Washington Apple Pi has shrink-wrapped manuals for virtually every computer Apple ever made, all untouched by human hands.)

The second answer is: printed documentation is expensive. It is expensive to write. It is expensive to print. It is expensive to ship. Per machine, the expense may not seem that great, but when you multiply that expense by millions of computers, the expenses add up.

As a result, while computers were getting more complex and worming their way into every corner of society, printed documentation all but vanished. Apple is not alone in this trend; printed documentation is almost an endangered species at most computer manufacturers. At least one Wintel company (there might be many, for all I know) includes exactly one printed document with their new computers: a license agreement stating that, if anything goes wrong, the user agrees that neither the manufacturer or Microsoft are to blame.

Pages and pages of stuff

As the printed documentation vanished, however, the amount of electronic documentation increased substantially. A staggering portion of the drive space consumed by Mac OS X is taken up with documentation: sample files, entire manuals in Adobe Acrobat (PDF) format, interactive documentation available through the Help menu, plus thousands of Web pages, QuickTime movie clips, sound files and graphic images. Additionally, for those who fire up Terminal and enter the character based world of UNIX, Mac OS X includes thousands of pages of “man” files, telling you in great (and often obscure) detail how to use the great (and often obscure) UNIX commands.

How do you discover all this wonderful documentation?

Mac OS X Help menu

At the top of the Mac OS X screen is the menu bar, and at the rightmost end of the menu is the Help menu. Yes, it is obvious — so obvious that only a tiny fraction of Mac OS X users have ever tried it. The Help menu is available almost all the time; only a few games go so far as to take over the entire screen and block it.

The Help menu is cleverly hidden in plain sight.
The Help menu is cleverly hidden in plain sight.

One thing to note: if you have an active Internet connection, selecting the Help menu will often trigger a pause — sometimes a lengthy pause — as your Mac looks out across the Internet to see if any of the documentation needs to be updated. This is good: your documentation is self-updating. But it can be disconcerting if you are expecting an instant response.

Because the Help menu is available globally, Apple has encouraged developers to use the same mechanism for their own programs. This can quickly amount to a fairly large library: not only do you get the standard Mac OS X help files, you’ll also see the Developer Help Center (if you’ve installed the optional Developer Tools), plus help libraries provided by various commercial, shareware and freeware authors. One noteworthy holdout: Microsoft does not use Apple’s Help menu. Instead, their documentation — for Internet Explorer, Word X, PowerPoint X, etc., is handled according to Microsoft’s guidelines, not Apple’s. One major downside to this: you must actually be running one of the Microsoft programs to read the documentation. In contrast, you can read about AppleWorks, for example, without actually opening the program.

Depending on what you have installed, your Help menu might be limited to the Mac OS X basics, or include topics related to the optional Developer Tools CD-ROM, or have entries for various other software packages you've installed.
Depending on what you have installed, your Help menu might be limited to the Mac OS X basics, or include topics related to the optional Developer Tools CD-ROM, or have entries for various other software packages you’ve installed.
Unix help

Help in the Unix world is available through “man” pages. There is actually a program within Unix called “man” that searches through its own databases to find relevant documentation on various Unix commands. So, for example, if you wanted to learn how to use the command for listing the contents of a directory, you would type:

man ls

which would give you pages and pages of information on how to use this seemingly simple but very versatile command.

The "clear" command isn't very exciting, but its accompanying man page is one of the shortest. Some commands have man pages that, if printed, would equal good-sized books.
The “clear” command isn’t very exciting, but its accompanying man page is one of the shortest. Some commands have man pages that, if printed, would equal good-sized books.

Naturally, the man command itself has a man page, and it is well worth a look. As with all documentation, it is best to learn how to read the documentation before you find yourself armpit deep in a crisis.

And then there are books

There are a fair number of “alpha geeks” who claim that all computer books are, by definition, out of date: by the time a book makes its way to press, the technology has moved on. With this as their guiding principle, they never buy books, calling them “dead trees.” Instead, they spend endless hours hunting down obscure Web sites, looking for information, and killing entire forests as they print out Web pages, man pages, PDF files and other forms of formerly electronic documentation. These pages are briefly skimmed, then trashed.

If you find utility more valuable than irony, give some thought to visiting a large bookstore, and checking out the computer books section. Almost any decent sized bookstore has a computer section today and, once you manage to wade through the Windows riff-raff, you’ll discover there are wonderful books available on almost any computer topic, from how to use iPhoto to how to write programs in Cocoa for Mac OS X. Unlike electronic documentation, you can stick bookmarkers in books, you can open up several books at once — with the computer turned off, even — and compare them, you can write your own notes in books, you can read them on a bus or a train, and you don’t have to go through special security precautions to take a book on a plane.

Don’t expect printed documentation to make a comeback. But do learn how to use the available electronic documentation, and check out your favorite local bookstore.

Western Pacific dragons and other real creatures

%d bloggers like this: