Examining documentation and help systems since 2002.
Contents
Special Reports
Subscription Feed
Gordon R. Meyer
Copyright 2002-2008
Favorite Sites
Too simple to believe
Macworld writes When Installing Software is Too Simple about the process of installing applications on Mac OS X, which involves dragging the application icon to your Applications folder, and how this one-step, no-installer process befuddles some Windows users. It's all about the expectations that users bring to the table and if things are too foreign, regardless of how simple they might be, they disbelieve the instructions they're given. A good example of needing to know your audience.
Part of the difficulty in the examples the article uses is that the installation instructions consisted of an illustration only. No words at all, which is a very challenging instructional task. After you read the article, check out the 2003 Usable Help Special Report Using Background Images in Mac OS X for technical details about the general technique.
Posted: Sunday, June 29, 2008 link to this item, respond to this item
Instructional search engine
It is cliche to write about the enormous impact the world wide web has had on society, so I'll try to avoid that as I point out that one of the professions most impacted is that of technical writers. In the not-so-distant past, the primary source of information about how to use a product was the manual provided by the manufacturer. More recently, third-party manuals have blossomed and are largely considered a must-have for learning how to use a new piece of consumer equipment or software. But beyond the so-called missing manual, the web offers a variety of instructional materials that are often easier to find, if not more honest, than any official or vetted channel. Created largely by customers, for customers, these "fourth-party" documents are everywhere.
The debut of Find How makes it even simpler to find good instructional material on the web. Instead of having to wade through Google results that include people asking unanswered questions and misinformation, you can search only for material that provides "how-to" information. KnowHow promises to offer links only to "trusted" sources of information. Virtually any topic you can think of is categorized and available; making reaching for the manual or Help menu even more of a measure of last resort.
See also: Help is the Last Resort and Fourth-Party Documentation.
Posted: Monday, June 23, 2008 link to this item, respond to this item
An example of simple Wiki-based instructions
The proliferation of wiki technology means that a lot of instructions, even complete sets of documentation, is appearing online and in editable format. If your company is doing this, but bogged down or intimidated with choices about how to style and format the instructions, just diving in anyway might be the best approach. To that end, check out these wiki-based instructions that are simple, mostly usable, and accomplished using an standard MediaWiki techniques. Notice that there's even a automatically-built advanced organizer at the top of the page. While this can surely be improved, the simplicity and ease of creation allows you to get started right away.
See also: Creating Help from a Wiki.
Posted: Friday, May 30, 2008 link to this item, respond to this item
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