<div id="popup_box_thanks" style="display:none" onClick="close_popup_thanks('popup_box_thanks', 'ts')"><br>Thanks for submitting your tip! All submissions are moderated by an editor before appearing online. We've reset the form so you can enter another tip. Or you can close the tip submission box. <div class="x_close" id="thanks_upper_right"><a href="javascript:void(0)" onmousedown="close_popup_thanks('popup_box_thanks', 'ts'); return true;">Close</a></div></div>
<div class="tbf_row"><div class="tbf_wide_extra_top not_bold">Please submit only technical tips that will help other TidBITS readers better use their Macs, iPhones, and related software and hardware. All product announcements should be sent to <a href="mailto:releases@tidbits.com">releases@tidbits.com</a>.</div></div>
<div class="tbf_left">URL</div><div class="tbf_right"><input type="text" value="" name="tip_link_url" tabindex="3"><span class="tip_description"><br>Enter the URL to a Web page that supports your tip.</span></div>
</div>
<div class="spacer"></div>
<div class="tbf_row">
<div class="tbf_left">Linked text</div><div class="tbf_right"><input type="text" value="" name="tip_link_label" tabindex="4"><span class="tip_description"><br>Enter the name of the page linked above.</span></div>
<div class="tbf_wide"><input type="submit" value="Preview Your Tip" name="preview_tip" onClick="fill_preview('tipbits_enclosure_preview', 'ts', this.form); return false;" tabindex="7"> <input type="submit" value="Send Us Your Tip!" name="submit_this_tip" onClick="handle_tip_submission('ts', '', this.form, 'tip'); return false;" tabindex="8"></div>
</div>
<div class="spacer"></div>
<div class="tbf_row">
<div class="tbf_wide"><span class="fine_print">When you submit a tip, you give us permission to use it. Read <a href="javascript:void(0)" onClick="generic_show_hide('tip_terms')">our terms</a> for more details. All submissions are reviewed before publication.</span></div>
<div class="tbf_wide"><span class="fine_print">Our terms: By submitting a tip, you agree to assign TidBITS Publishing Inc., a non-exclusive, worldwide, perpetual license to reproduce, publish, and distribute your tip in connection with the TidBITS Web site and associated products in any media. You agree that you created the content you submitted, and that you have the right to assign us this license. You give us permission to use your name, but your email address won't be publicly displayed or shared. We review all submissions before publication, and reserve the right to select which submissions we feel are appropriate for our readers and to edit those we publish.</span></div>
<div id="comment_thanks" style="display:none" onClick="close_popup_thanks('comment_thanks', 'comm')"><br>Thanks for submitting a comment! Please check your email for a link that, when clicked, will verify that you're a real person and cause your comment to appear immediately. <div class="x_close" id="comment_upper_right"><a href="javascript:void(0)" onmousedown="close_popup_thanks('comment_thanks', 'comm'); return true;">Close</a></div></div>
<div class="tbf_wide"><span class="fine_print">Our terms: We reserve the right to edit or delete any comment, so please post thoughtfully. We use your email address <i>only</i> to send you a one-time verification message confirming that you posted this comment. We also store your address to allow you to verify using other Web browsers in the future. For more info, see our <a href="http://db.tidbits.com/privacy.html">privacy policy</a>.</span></div>
<li><a href="/feeds/tidbits.rss" title="Subscribe via RSS" class="gettb">RSS <img src="/images/feed-icon-12x12.gif" width="12" height="12" border="0" class="nav_img" alt="Subscribe via RSS"></a></li>
<li><a href="http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewPodcast?id=276986548" title="Subscribe to the podcast" class="gettb">Podcast <img src="/images/feed-icon-12x12_podcast.gif" width="12" height="12" border="0" class="nav_img" alt="Subscribe to the postcast"></a></li>
<li><a href="http://www.twitter.com/TidBITS" title="Get Article Updates via Twitter" class="gettb">Twitter <img src="/images/feed_icon_12x12_twitter.png" width="12" height="12" border="0" class="nav_img" alt="Get Article Updates via Twitter"></a></li>
<li><a href="http://www.facebook.com/pages/TidBITS/195314925519" title="Go to the TidBITS Page at Facebook" class="gettb">Facebook <img src="/images/feed_icon_12x12_facebook.gif" width="12" height="12" border="0" class="nav_img" alt="Go to the TidBITS Page at Facebook"></a></li>
<li><a href="javascript:void(0)" title="Sections" class="tabhead" onClick="return showhide('articleslist')">Sections <span id="articleslist_triangle"><img src="/images/nav_triangle_open.gif" width="9" height="9" border="0" class="navtriangle" id="articleslist_tri_image" alt="Click to show or hide the contents of this section."></span></a></li>
<li><a href="javascript:void(0)" onClick="return showhide('stafflist')" title="Staff" class="tabhead">Staff <span id="stafflist_triangle"><img src="/images/nav_triangle_closed.gif" width="9" height="9" border="0" class="navtriangle" id="stafflist_tri_image" alt="Click to show or hide the contents of this section."></span></a></li>
<li><a href="javascript:void(0)" title="Issues" class="tabhead" onClick="return showhide('issuelist')">Weekly Issues <span id="issuelist_triangle"><img src="/images/nav_triangle_closed.gif" width="9" height="9" border="0" class="navtriangle" id="issuelist_tri_image" alt="Click to show or hide the contents of this section."></span></a></li>
<li><a href="javascript:void(0)" onClick="return showhide('abouttidbits')" title="About TidBITS" class="tabhead">About TidBITS <span id="abouttidbits_triangle"><img src="/images/nav_triangle_closed.gif" width="9" height="9" border="0" class="navtriangle" id="abouttidbits_tri_image" alt="Click to show or hide the contents of this section."></span></a></li>
<div class="center_top">Thoughtful, detailed coverage of the Mac, iPhone, and iPad, plus the best-selling <a href="http://www.takecontrolbooks.com/?pt=TB-TAGLINE" style="color:yellow">Take Control</a> ebooks.</div>
<!-- begin centercolumn -->
<div id="centercolumn">
<!-- begin rightcolumn_container -->
<div id="rightcolumn_container">
<!-- begin rightcolumn -->
<!-- rightcolumn is embedded within centercolumn so featured text wraps around it -->
</div><!-- end tearoffbox_wide_container for watchlist items -->
<!-- begin tearoff box wide -->
<div class="tearoffbox_wide_container">
<div class="tearoffbox_wide_tips">
<div class="tip_display">
<div class="tips_sponsor_logo">
</div>
<h6>How to Know Your iPod Model</h6>
<p><p>If you have an old iPod but aren't sure exactly which model it is, check the info at the Web page linked below. You'll find lots of photos and information that will help you determine exactly which model you have.</p></p>
<div class="tbf_wide_80" id="hc_rc_3544">To help us avoid automated posts and misuse of our site, please enter the words below.</div><div class="x_close_row" id="hc_upper_right2_3544"><a href="javascript:void(0)" onmousedown="HidePopupContent('hc_3544', 'hc', '3544'); return true;">Close</a></div>
<div class="featured_meta"><div class="meta_article">04 May 1998 | <a href="/article/4865?print_version=1">Print <span class="shift_up"><img src="/images/printer_icon.gif" alt="Printer-Friendly Version of This Article" border="0" width="9" height="10"></span></a></div></div>
<div id="article_box_3544"><P>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.</P><P>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.</P><P>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.</P><P>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).</P><P><<A HREF="http://www.microsoft.com/office/ork/">http://www.microsoft.com/office/ork/</A>><BR><<A HREF="http://mspress.microsoft.com/prod/books/1329.htm">http://mspress.microsoft.com/prod/books/ 1329.htm</A>></P><P>Short of one truly confusing stylistic issue (on the Mac, you don't <EM>click</EM> menus, you <EM>choose</EM> 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</P><P><STRONG>Manual Migration</STRONG> -- 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.</P><<A HREF="http://www.casadyg.com/products/grammarian/">http://www.casadyg.com/products/grammarian/</A>><P>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.</P><P>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?</P><P>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.</P><P>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!"</P><P>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.</P><P>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.</P><P><STRONG>Switch to Automatic</STRONG> -- Far be it for me to moan about the state of documentation without offering suggestions for ameliorating the situation.</P><P>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.</P><P>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.</P><P>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.</P><<A HREF="http://www.dantz.com/sp/808.html">http://www.dantz.com/sp/808.html</A>><P>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.</P><P><STRONG>With an Open Checkbook</STRONG> -- 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.</P><P>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.</P><P>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 <A HREF="http://www.tidbits.com/tb-issues/TidBITS-333.html">TidBITS-333</A>) 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.</P><<A HREF="http://db.tidbits.com/article/00963">http://db.tidbits.com/article/00963</A>><P>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.</P><P>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.</P><P><STRONG>Documentation on a Shoestring</STRONG> -- 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.</P><<A HREF="http://db.tidbits.com/series/1039">http://db.tidbits.com/series/1039</A>><P>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.</P><UL><LI><P>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.</P><LI><P>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.</P><LI><P>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.</P><LI><P>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.</P><LI><P>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.</P><LI><P>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.</P><LI><P>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.</P><LI><P>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.</P></UL><P>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.</P><!-- The Death of Documentation Adam C. Engst --></div>
<!-- end article text -->
<!-- PayBITS -->
<p> </p><div class="sponsorbox">
<div class="sponsortext"><A HREF="http://www.tidbits.com/about/support/contributors.html"><IMG SRC="http://db.tidbits.com/images/badges/tb-house-ad.gif" ALT="" HEIGHT="50" WIDTH="50" BORDER="0" ALIGN="left"></A>READERS LIKE YOU! Support TidBITS with a contribution today!<BR /><<a href="http://www.tidbits.com/about/support/contributors.html">http://www.tidbits.com/about/support/contributors.html</a>><BR />Special thanks this week to John & Nichola Collins, Chris Williams,<BR />John K. Lilley, and Honeymoons By Sunset for their generous support!
