Examining documentation and help systems since 2002.
Contents
Special Reports
Subscription Feed
Gordon R. Meyer
Copyright 2002-2008
Favorite Sites
Error messages that help
Ideally, tech writers are involved in writing the error messages, warnings, and alerts that a product displays for users. But it's a task that is often left towards the end of a project and sometimes the best that can be done is to make sure that the messages are grammatically correct and don't contain spelling errors. If there is time, however, a recent IBM study suggests that error messages should be regarded systematically, not individually, as multiple messages can be misleading if they're not well-planned.
In Error Messages: What's the Problem? Paul Maglio and Eser Kandogan observe:
Error, warning, status, and other information messages play a fundamental role in the way people reason about computer failures. By examining how computer users really behave, we found that messages in fact determine what users think and do when confronted with problems. That is, messages do not simply alert users to problems, they guide problem-solving behavior.
Read the article at the ACM Queue website.
See also: Recognizing an Error When You See It.
Posted: Sunday, May 11, 2008 link to this item, respond to this item
See Dick sudo
Although this is an advertising piece, the instructional elements and unusual approach of Mommy, Why Is There a Server in the House? will bring a smile to any technical writer's face. It's fun to see a big company like Microsoft show a little personality, even while hiding behind a mask.
Posted: Friday, April 25, 2008 link to this item, respond to this item
Contextual cues for the user
Mac OS X features built-in "Help Tags" (similar to Tool Tips) that label, and sometimes explain, interface elements. But sometimes you want to present more than just a few words of text or direct users to interface elements that are not directly under the mouse pointer.
The application Lab Tick solved this problem by implementing an open source "attached window." It's attractive and solves this type of problem in an interesting way. See Matt Gemmell's site for the source.
See also: Context-Sensitive Help Primer and Adobe's Elemental Help.
Posted: Friday, April 18, 2008 link to this item, respond to this item
Keyword access to websites
Cabel Sasser writes, in Japan: URL's Are Totally Out, about his observations that search terms are beginning to replace URLs in advertising. That is, instead of an ad including a website address such as "www.usablehelp.com" it shows a text input field containing "Usable Help" and a Search button.
Given the complexity of some URLs, this is probably an easier way to remember how to get to a site, but it does certainly depend on the search engine giving prominence to the advertiser's intended destination. Google, of course, does a pretty good job of this already. (And with keyword advertising to supplement the print ads, you can probably ensure even greater success.)
The fascinating Google Hot Trends webpage often includes URLs, so it apparently isn't uncommon for users to type fully-qualified and legitimate addresses into a search, even though it inevitably results in an extra click to get to the real destination.
This idea can be applied to onscreen Help by giving users search phrases instead of hierarchical paths to specific topics. In the manual for the MacBook Air, Apple provides search phrases for the user to enter into Mac Help.
If you're an Apple Help author, use the ExactMatch feature to ensure that the best pages for the suggested phrase are shown at the top of the results list. Information about implementing ExactMatch searching is in the latest revision of the Apple Help Programming Guide.
See also: Latest Info about Apple Help, Ins and Outs of Indices and Better Learning Through Better Searching.
Posted: Thursday, April 10, 2008 link to this item, respond to this item
Why customers write their own documentation
Nearly every tech writer has experienced finding customer-produced documentation that is adapted from the onscreen help or manual that came with the product. Sometimes it is nearly identical but has had customer-specific information added, which allows their users to have concrete answers to questions like "See your system admin for information about the IP address you should enter." But on some occasions, the re-write is a hatchet-job with little discernible improvement. While I can't always explain the latter, a 2007 survey of free documentation projects provides insight into the motivation of some independent technical communicators.
Posted: Thursday, April 3, 2008 link to this item, respond to this item
Updated job aid creation tool
ScreenSteps , a product of Blue Mango Learning Systems, was recently updated with plenty of new features and an array of different versions and prices. It still allows you to capture and document discrete steps, but now includes more publishing options, the ability to more easily update existing instructions, and offers a limited-ability free version. It's available for both Mac OS X and Windows. Watch the 3 minute "Quick" Intro video to discover if this product is useful for you and your work.
Also debuting with the new version is the website ScreenSteps Live. Declaring that "Traditional documentation is broken. We 're going to fix it," the site provides a public repository for ScreenSteps-created documentation.
See also Easy Job Aid Creation Tool.
Posted: Friday, March 21, 2008 link to this item, respond to this item
Acknowledging the medium
Writers and designers who learned to optimize their work for the printed page sometimes struggle with designing documents that work well onscreen. Many find the differences to be frustrating and sometimes feel like their "settling" for an inferior presentation of their work. But another approach is to embrace the additional capabilities that onscreen presentation provides, and find ways to allow it to perform in ways that surpass printed matter. Well-designed web sites are one example, but there's also an interesting idea demonstrated in the PDF-based "application map" for Mind Burn. (PDF Link) While the design isn't particularly striking, in my opinion, it's refreshing to see a PDF that avoids a paper-centric layout and invites you to use the inherent high-quality zoom tools to focus on the information you're interested in seeing. How else might PDF break free of its paper-based roots and become truly useful for onscreen documentation?
Posted: Wednesday, March 12, 2008 link to this item, respond to this item
One-on-One envy
sMany technical writers, unless they happen to work in a training group, don't get very much opportunity for personal contact with their readers. Additionally, the corporate voice that most documentation uses is strictly non-personal and personality free. So, reading this Mercury News article (registration might be required) about Apple's success with personalized, individual training with their One to One program is a fun diversion. It might bring to thoughts ways that documentation might be made more interactive and personalized, too.
Posted: Saturday, March 8, 2008 link to this item, respond to this item
Apple mockumentation
Sometimes a company is so consistent in their style and design that they inspire imitators and satirists alike. To that end, the website for the fake product iHam 5Js is a most impressive effort. There are plenty of subtle and clever points to appreciate, but don't miss the multilingual PDF manual (available at their site), it puts plenty of "real" manuals to shame.
See also More Mockumentation from VW and Learning from Mockumentation.
Posted: Sunday, March 2, 2008 link to this item, respond to this item
This PDF brought to you by...
If you're in the situation where your documentation must at least break even, if not turn a profit, then you'll almost certainly be interested in Adobe's service that brings dynamic advertising to PDF documents. It works similar to Google's AdWords, in that Adobe inserts the ads based on the nearby content of your PDF. You're paid every time a reader clicks an ad. Whee! It's like free money falling from the sky.
It might sound wacky, but Kevin Kelly is using it to offset the costs of distributing his True Films ebook.
See also: Sponsored Help.
Posted: Tuesday, February 19, 2008 link to this item, respond to this item
Helpful setup help
Everyone knows the old saying about first impressions, but it's rarely applied to software. The first time your customer opens your application they'll form an instant opinion about your product. It's responsiveness, user interface, and friendliness are exposed, and judged, in the first few minutes of use.
Two leading third-party developers for the Mac have recently written about the design of the setup assistants for their applications, and there is much to learn from their discussion. You'll find how they address different audiences, how wording is critical to success, and the decisions they made in favor of simplicity and ease of use. Begin with On the Design of the First-Run Assistant from Brent Simmons, then read Daniel Jarkut's Designing for the First Launch.
See also: Tips about Tips, Context-sensitive Help Primer, and Context Adds Life.
Posted: Monday, February 4, 2008 link to this item, respond to this item
Web 2.0 and humor
Nick Bradbury writes Funny Error Pages Suck and explains how misplaced humor can serve to upset customers.
No, it's not funny when a site you're relying on to do your job or communicate with others goes down. I don't know about you, but I wouldn't want my operating system, word processor, or development tool to tell me jokes when they crash.
For other perspectives on the use of humor in documentation and onscreen messages see: A Funny Manual that Works and Click, Drag, Smile.
Thanks to Brent Simmons for the link.
Posted: Friday, January 25, 2008 link to this item, respond to this item