A Big Minus for ZipPlus — Iomega recently revised the compatibility guidelines for the ZipPlus drive, and these guidelines suggest that Iomega either dropped the ball when testing the drive or has a blatant disregard for reality. The ZipPlus can detect whether the drive is connected to a SCSI or parallel port using a special blue AutoDetect cable. Failure to use that cable, use of "any cable converter or gender changer," or use in a multiple-device SCSI chain, could cause system incompatibilities and data loss. Iomega also specifies that the ZipPlus not be used with any PowerBook, regardless of the cable. What’s next, a requirement that users store the ZipPlus in a cool, dark place away from loud noises? We hope Iomega will provide a technical solution to these problems quickly. [JLC]

<http://www.iomega.com/product/zip/zipplus.html>

<http://www.iomega.com/support/techs/zip/ zpluswp.html>

Baby, You Can Drive My Tape — Dantz Development has released the free Retrospect 4.0 Driver Update 1.4, which adds support to Retrospect for a number of new CD-R drives, tape drives, and autoloaders (devices that swap among multiple tapes automatically). As the leading Macintosh backup application, Retrospect 4.0 already supports a large number of backup devices; for a full list, see Dantz’s Backup Mechanism Compatibility List. The Retrospect Driver Update 1.4 is a 111K download. [ACE]

<http://www.dantz.com/upgrades_and_updates/ rdu.html>

<http://www.dantz.com/backup_hardware/mech_ list.html>

Mailsmith Emerges from the Forge — Bare Bones Software today announced the release of Mailsmith 1.0, the company’s long-awaited email client program. Although the market for email programs would appear crowded, what with Emailer, Eudora, Netscape Communicator, Outlook Express, QuickMail Pro, and others, Mailsmith promises some unusual features. Mailsmith offers multi-threaded processing that enables it to send, receive, and filter mail while you continue to work; filters with multiple criteria and multiple actions; "fuzzy" searching; grep pattern matching in searches and filters; database-based mail storage; full OSA scripting and recording; and the essential text-editing features from BBEdit. Mailsmith has a suggested retail price of $79; existing BBEdit owners can purchase it for $59; and discounts are available for users of other email programs. A demo is available from the Bare Bones FTP site, which isn’t currently accepting connections. [ACE]

<http://web.barebones.com/press/msmithpr.html>

<http://web.barebones.com/products/msmith/ msmith.html>

HP Inkjets to be Mac Compatible — Now that Apple’s StyleWriters are history, Apple and Hewlett-Packard (HP) announced last week that future inkjet printers from HP will be compatible with the Mac OS, and that Apple will resell some HP inkjet printers directly to customers in education, presumably so schools can order machines and printers with a single purchase order. Printers with the HP brand should also be available to customers through direct channels like the Apple Store later this year. Mac OS drivers for the HP printers will apparently not be engineered by Apple or HP, which is both good and bad news since Apple’s StyleWriter drivers tended to be good, but HP’s Mac OS printer drivers were often a mixed bag. Instead, Mac OS drivers for HP printers will come from Infowave – makers of products like PowerPrint, which lets Macs use a wide array of PC printers, and StyleScript, a PostScript interpreter for inkjets – and may include support for Apple’s ColorSync color matching technology. [GD]

<http://www.apple.com/pr/library/1998/apr/ 28hp.html>

<http://www.infowave.net/whats_new/html/04_06_ 98.html>

Add a VISE to Your Freeware or Shareware — MindVision Software has announced a free license that makes their Installer VISE installation software available for free to shareware and freeware developers. Installer VISE 5.0.1 offers numerous advanced features, such as a Web-based installer, precise icon positioning, user-defined forms, integration with MindVision’s Updater VISE technology, and online product registration. At a time when Apple is changing its developer support programs to focus on the 100 largest Macintosh developers (see "Furor Over Developer Programs & QuickTime" in TidBITS-425), it’s good to see other members of the Macintosh industry helping small developers. [ACE]

<http://www.mindvision.com/Pricing/ shareware.html>

<http://www.mindvision.com/News/Mac5.0/ ComingSoon.html>

<https://tidbits.com/getbits.acgi?tbart=04821>

Eudora Internet Mail Server 2.1 Released — Qualcomm has released a free updater that takes Eudora Internet Mail Server 2.0 or 2.0.1 to version 2.1. Important new features include IP multihoming support under Open Transport 1.3, remote viewing and manipulation of the outgoing message queue, import and export of users, and assigning IP address restrictions on mail relaying. Also included are user interface changes; bug fixes; and performance improvements, notably when downloading information to the EIMS Admin program. Eudora Internet Mail Server 2.0.1 is available solely online for $199, or $299 with a 5-pack of Eudora Pro. The free updater is a 1.6 MB download. [ACE]

<http://eudora.qualcomm.com/eims/>

<http://eudora.qualcomm.com/eims/updaters.html>

Nearly three years after the last Macintosh-specific virus appeared on the scene, a new piece of Macintosh malware (code designed with malicious intent) has appeared. The worm, which is designed to overwrite data files, has spread rapidly in the desktop publishing community in Hong Kong, where it was first spotted. (Unlike a virus, which must attach itself to other software in order to function, a worm executes by itself.)

The worm, which anti-virus analysts have dubbed Autostart-9805, takes advantage of a feature in QuickTime 2.0 and later that enables CD-ROMs to start a program immediately upon insertion. In QuickTime 2.5 and later, the QuickTime Settings control panel lets the user disable this feature.

Inner Workings — Analysts say the worm can be transmitted via almost any HFS or HFS+ disk volume, including floppy disks, most removable cartridge drives, magneto-optical disks, recordable CD disks, hard disks, and even mountable DiskCopy or ShrinkWrap disk image files. The worm only operates on a PowerPC system running the Mac OS, and will only initially infect a computer that’s running QuickTime 2.0 or later with the CD-ROM AutoPlay feature enabled.

Infected disks contain an invisible application file named DB of type APPL and creator ???? in the root directory, and the AutoPlay attribute is set in the disk’s boot blocks. When the infected disk is mounted, the DB application launches and copies itself to the Extensions folder of the active System Folder. The copy, also an invisible file, is named Desktop Print Spooler and its type is appe (don’t confuse this file with the visible and legitimate Desktop Printer Spooler extension). The worm then restarts the computer, and reloads into memory via the invisible Desktop Print Spooler, which runs as a faceless background application and doesn’t appear in the Application menu.

About every thirty minutes, the worm examines all mounted volumes, and attempts to infect any that aren’t infected by copying itself back to the root directory as DB with AutoPlay enabled. It then searches mounted volumes for files whose names end with "data", "cod", or "csa" and whose data forks are larger than 100 bytes, or files ending with "dat" that are larger than about 2 MB. When it finds such a file, the worm overwrites approximately the first 1 MB of the data fork with garbage.

Are You Infected? So far, anti-virus experts don’t believe AutoStart-9805 has spread much beyond the desktop publishing community in Hong Kong, so it should be possible to keep it from spreading much farther. Check with your anti-virus utility publisher for the latest updates, keeping in mind that outdated virus definition files are useless! Visible symptoms you can check for include:

• The system unexpectedly restarts after mounting a volume, which is when the initial infection occurs.

• The application name DB flashes briefly in the menu bar when the application launches.

• A disk volume contains an invisible application file named DB in the root directory, or the invisible Desktop Print Spooler file in the Extensions folder. Use ResEdit, Norton Disk Editor, the Mac OS Find File utility (press Option while clicking on the Name menu to reveal a Visibility item), or a similar tool to search for invisible files.

• A process named Desktop Print Spooler is visible when using tools like Process Watcher or MacsBug.

• Extensive, unexplained disk activity every 30 minutes.

  
  

Prevention — The risk of a new infection can be effectively eliminated by disabling the CD-ROM AutoPlay feature in the QuickTime Settings control panel in QuickTime 2.5 or later, though this will not help if the system is already infected. It also will not prevent an infected Mac from creating the invisible DB files on a system whose volumes are shared on a network. Versions of QuickTime prior to 2.5 lack the means to disable the AutoPlay feature, so Apple’s QuickTime group recommends upgrading to QuickTime 2.5 if you have an older release. Disabling Audio CD AutoPlay is unnecessary, as ordinary audio CDs cannot carry this worm.

<ftp://ftp.info.apple.com/Apple_Support_Area/ Apple_SW_Updates/US/Macintosh/System/ QuickTime/Older_QuickTime/>

Utilities — Dr. Solomon’s Anti-virus Toolkit and Virex have been updated to handle this worm, and Symantec expects to release an update for SAM. John Norstad’s freeware Disinfectant cannot detect this problem, so he recommends using an up-to-date commercial utility that does. He plans to make an announcement soon as to whether Disinfectant will be updated to handle Autostart-9805.

<http://www.drsolomon.com/products/avtk/ps_ mac.html>

<http://www.drsolomon.com/products/virex/>

<http://www.symantec.com/sam/>

<ftp://ftp.nwu.edu/pub/disinfectant/>

Apple’s QuickTime evangelist Charles Wiltgen expressed the company’s delight that "the commercial utility vendors have responded to this as quickly as they have." Wiltgen encourages QuickTime users to disable the CD-ROM AutoPlay feature unless they have a specific need for it, and to obtain and use a current anti-virus utility.

I have a song stuck in my head, only the words are slightly twisted. I keep hearing Pete Seeger singing, "Where have all the manuals gone, long time passing?" I’m worried that it will be a while before I stop mentally humming along.

Aside from this week, when I pleasantly surprised by the excellent WebSTAR 3.0 manual written by Avi Rappoport, I can’t remember the last time a product’s documentation really impressed me. Heck, many products these days don’t even come with printed manuals. What has happened to the fabulous manuals of yesteryear, the books that taught something that wasn’t obvious from the interface? I admit that well-done manuals have always been the exception rather than the rule, but I remember a few that stood out. The first Suitcase manual had an excellent discussion of how fonts worked on the Mac. And early versions of the Norton Utilities manual provided detailed information on Macintosh disk structures.

Today’s manuals, when they exist on paper at all, more closely resemble booklets than books. Size alone is of course not an indication of quality, but no one is more capable of producing accurate and comprehensive reference information than the company that creates a program. Independent books can be better written and organized, and more honest about a program’s shortcomings, but most authors can’t obtain the access to developers and testers that in-house writers enjoy.

Look at the just-released Microsoft Office 98. It’s composed of three complex, powerful programs in Word, Excel, and PowerPoint, and yet the only printed documentation is a trio of slim (248 pages for Word, 244 pages for Excel, and 160 pages for PowerPoint) "Getting Results" manuals that provide task-based help to experienced users. The introduction to the Word manual even says, "The people who will find this book most useful are those who have been using Word for a while and who can usually do what they want to do with the application." Novice users are pointed at the 50-page Getting Started chapter, which covers only the absolute basics, whereas advanced users and system administrators are sent to the Web-based Microsoft Office Resource Kit (also available as a $60 book from Microsoft Press).

<http://www.microsoft.com/office/ork/>

<http://mspress.microsoft.com/prod/books/ 1329.htm>

Short of one truly confusing stylistic issue (on the Mac, you don’t click menus, you choose items from them), Office’s documentation isn’t even bad – task-based help is extremely valuable. It’s just incomplete, since it lacks the serious reference information that Microsoft used to provide and that a number of TidBITS readers have already missed. The Microsoft Office documentation is only one of many examples of skimpy documentation I’ve seen of late, such as Qualcomm’s Eudora Pro 4.0 manual

Manual Migration — So where have these manuals gone, and why have they left us? The primary reason is cost. It takes money to hire talented technical writers to produce a useful manual, not to mention printing costs. Large manuals also increase the weight of the packaging, resulting in increased shipping charges. As a case in point, Casady & Greene’s recently released $80 Grammarian comes with an electronic manual; the printed manual costs an additional $15.

<http://www.casadyg.com/products/grammarian/>

But if these restrictions of the physical world were the only limits on shipping excellent manuals, we’d see well-done electronic documentation, and for the most part, electronic documentation is as bad as – or worse than – what makes it to paper these days. I think the reasons for lousy documentation run deeper.

Apple deserves a small portion of blame for this trend toward poor documentation because by forcing Macintosh programs to look and work much the same for basic tasks, Apple has made programs easier to use. Systems that lack conventions, especially if they also lack graphical discoverability (think of the DOS or Unix command line) are more likely to require documentation – how else would anyone figure them out?

We users must also shoulder some blame. After all, the mantra of the Macintosh user has always been, "I never read manuals." For the most part, we don’t. Users expect software to be so easy to use that the manual is merely a superfluous appendage. Some products are that simple, but many aren’t; too bad it’s cheaper to ship a pamphlet that makes a product look simple, even when it’s a complex, powerful program.

I’ve seen the same trend in computer books. As the author of a bona-fide tome – Internet Starter Kit for Macintosh – I was astonished at how many people wanted less information. They weren’t offended at the cost; they just didn’t want to read the entire book and didn’t like the idea of skipping clearly labeled sections that didn’t apply to them. "Fascinating," I thought. "If I took this to the logical extreme, people would pay $30 for no information at all!"

I’d also like to pin the tail of blame on the Internet. As much as I believe in the leveling force of the Internet as a democratic publishing medium, much of what I see online lacks the polish of professionally written, organized, and edited text. Lack of polish is acceptable if the quality of the information remains high, but much of what’s on the Internet is of such poor quality that it lowers the bar for what’s expected, especially for electronic documentation.

Finally, the people who write manuals generally have their facts correct and are usually competent, if not inspired writers. But they’re not teachers, people who make their living working on the best ways explain complex topics to a wide range of audiences. It’s not easy to figure out the best way to phrase and organize information, and the needs of the reader must always remain in mind. Those who lose sight of helping the reader learn inevitably turn out a mediocre manual.

Switch to Automatic — Far be it for me to moan about the state of documentation without offering suggestions for ameliorating the situation.

First, based on comments I’ve received about my books, I believe all writing should have a voice. Show some attitude and let a personality come through in documentation. One fascinating example of this problem is Microsoft Office 98’s documentation. The printed manuals and the online help are pretty dry, but one of the program’s major features is the addition of Max, the personable Mac-like Office Assistant. Although Max’s antics can annoy at times, those who like him do so because he’s fun. The manuals and online help would benefit from a touch of that personality.

Second, online documentation requires consideration and care to do well. The first decision involves the electronic format, and you should think about that before starting the documentation process. For instance, many companies just print their manuals to a PDF document and ship Acrobat Reader along with the software. That’s a cop out and in most cases results in almost unusable documentation.

If you use PDF, create a design that can be read onscreen as well as a design that can be printed. The onscreen version should use common screen fonts and utilize PDF features like navigation bookmarks and links. PDF files should also mention Acrobat’s searching capabilities – you can’t assume people are expert Acrobat users. Searching is important – if you use some other electronic format, make sure it’s searchable! An example of good PDF-based electronic documentation is the manual for Dantz Development’s new Retrospect Express. Although it’s a little disappointing that the program comes with only 12 pages of printed documentation (for each of English, French, and German), the online manual is complete, well-written, and designed for the screen (though it includes printing tips too). It also provides navigation bookmarks and even has a "hot" table of contents and index in which you can click headings to jump directly to the associated page.

<http://www.dantz.com/sp/808.html>

Although PDF is relatively easy to create, especially for an electronic version of a paper manual, HTML may be more common these days. However, an HTML version of a manual isn’t necessarily ideal either. Web browsers can search only in a single page, not through a set of Web pages (though you could link to an online search engine on your Web site). Also, provide plenty of navigational controls, since otherwise moving around within the manual will prove frustrating.

With an Open Checkbook — Large companies have the least excuse for shipping substandard manuals, especially with their flagship products, which often retail for hundreds of dollars. Good documentation may increase development costs, but these companies already spend vast sums of money on documentation.

For large companies, I think the solution is simple. Bring in a professional author to write the manual. Just look at all the independent books out there on any given program. Many of those books will sell no more than 10,000 or 15,000 copies, making the author between $10,000 and $20,000, before taxes. A large, successful company could easily spend $40,000 or $50,000 to hire someone (or even a group) to produce a top-quality manual. Sure, the author won’t have a chance at royalties from a best-seller, but many publishing companies are currently pushing authors to write books as "work for hire," where royalties never enter the picture anyway.

The argument that there’s more than just writing involved in creating a manual doesn’t fly either. Experienced authors often do much more relating to book production than just writing. Some publishers make authors responsible for the index (professional indexers are always better than amateurs – see David Holzgang’s article "The All-Important Index" in TidBITS-333) and require authors to submit PostScript files. For instance, for my Eudora Visual QuickStart Guide, I did the writing to Peachpit’s style, laid the book out in a QuarkXPress template file, convinced Tonya to do the copy editing, and paid an indexer to compile the index.

<https://tidbits.com/getbits.acgi?tbart=00963>

If a large company isn’t interested in finding an individual author, why not contract with a publishing house for the same services? Adding a publisher would increase the cost, but might result in an even higher quality manual, since publishers have professional editors and production departments. At the very least, publishers are already publishing these books. I’d happily replace most manuals I’ve seen of late with Peachpit’s Visual QuickStart Guides, although they’re task-oriented and don’t include detailed reference information.

Producing a good manual can decrease technical support costs, but many large companies now charge for support, so reducing the need for support may not be an advantage. In fact, conspiracy theorists might posit that shipping a lousy manual will increase support’s bottom line.

Documentation on a Shoestring — What about small companies? Although the possibilities might seem grim, small companies don’t face the same concerns because they’re likely to produce less complex products. This isn’t to say that small products can get away without documentation. A good ReadMe file is essential, particularly for software distributed solely via the Internet. Tonya has written several articles on this topic over the last few years, mostly in response to being irritated by lousy ReadMe files.

<https://tidbits.com/getbits.acgi?tbser=1039>

Essential though a ReadMe may be, most programs also require manuals. Although small companies probably can’t afford a professional writer, allow me to suggest this simplistic template for a manual. Don’t feel bound by it, but if you can fill in these sections, you should end up with something acceptable.

• Table of Contents: They’re short and easy, and always worth doing. If a table of contents seems too short or the chapter titles aren’t sufficiently descriptive, add a sentence or two of explanation beneath each title.

• Introduction: Explain what your program does and why someone would want to use it. Don’t assume that people know this information already. Providing usage examples may help users get started.

• Requirements & Installation: Always list the system requirements for your program so users don’t install before realizing their Mac can’t run your software. After that, turn to installation, making sure to address previous users if it’s an upgrade. Always provide a list of exactly what’s installed where, especially for items in the System Folder.

• Getting Started: In this section, provide step-by-step instructions for performing basic tasks in your program. Don’t explain everything; instead provide a tutorial that helps users gain a feel for how the program works and what they can use it for. Sophisticated users will skip the tutorial, but given that the Step-by-Step chapter in Internet Starter Kit for Macintosh was always extremely popular with novices, I’m convinced of the utility of this section.

• Reference: This is the trickiest section. You don’t want to document obvious stuff that exists in all Mac programs (like how to quit); instead look to explain capabilities unique to your software. You can organize the reference section so it documents menu commands and dialog boxes; however, it also pays to organize documentation around what people can do with the software, and then tell them how to do it, regardless of what commands must be employed. In particular, cover features that are somewhat hidden.

• Troubleshooting: Even if your software is perfect, it’s running in an imperfect world. Always discuss what might go wrong and how to troubleshoot problems.

• FAQ: Although a Frequently Asked Questions list may seem strained in the first version of a product (make up the questions and answers), keep track of questions for future versions. Even if you decide not to put your entire manual online, put the FAQ on the Web – FAQs are tremendously helpful to existing and potential users.

• Index: I know I said you should hire a professional indexer if possible, but if you don’t have the budget for it, try to do an index on your own anyway. Beware of automated index generation tools in word processors and desktop publishing programs, since a good index doesn’t include each instance of a given word; instead, it indexes appropriate instances of important words and concepts.

  
  

I won’t pretend that creating useful documentation is easy, but I think it’s a worthwhile effort, especially for increasing customer satisfaction and reducing technical support costs, which can be significant especially for smaller companies and individual developers.