Examining documentation and help systems since 2002.
Contents
Special Reports
Subscription Feed
Gordon R. Meyer
Copyright 2002-2009
The weight of history
In Why Text Messages Are Limited to 160 Characters we learn that the length was determined, in part, by looking at messages on postcards and those sent by Telex. Just as today's help systems are burdened with notions from the world of books, such as chapters and page numbers, decisions made to fit specific situations have a tendency to live on far past their origination, and some would argue, usefulness.
Posted: Sunday, June 28, 2009 link to this item, respond to this item
Apple Help and iPhone at WWDC
Joe Welinske, the driving force behind Writers UA, has posted notes about attending his first Apple developer's conference (WWDC). Posted in three parts, Welinske describes his experience writing Help and UI wording, wonders about possible gender bias, and notes some details about Apple Help in Snow Leopard. And much more, too.
Posted: Friday, June 19, 2009 link to this item, respond to this item
What value do you add?
In a world where instantaneous and responsive documentation is readily available, albeit from amateurs, how can professional publishers remain relevant? In Four Roles for Publishers: Staying Relevant When You Are No Longer a Gatekeeper - Tools of Change for Publishing, it's all about quality.
Posted: Thursday, June 18, 2009 link to this item, respond to this item
Instructional video delivers life
Not that further evidence is needed that instant access to online instruction is a good thing, but here's a unique story that should warm the heart of any instructional designer. According to BBC News, a man in Cornwall used YouTube to learn how to deliver a baby when his wife suddenly went into labor. See YouTube Helps Man Deliver Baby for the details.
Posted: Sunday, May 31, 2009 link to this item, respond to this item
Authoring Apple Help with Voodoo Pad
Philippe Casgrain outlines how he has integrated Voodoo Pad with his development environment to automatically export and build Apple Help for his new product, iChibi. I'm a big fan of Voodoo Pad and use it for all my working notes when I'm documenting a product. It's also an excellent way to build documentation that will be exported to HTML. Casgrain's tips are welcome because they ensure that your help is exported each time a build of the product is initiated.
See also: Authoring Apple Help with OmniOutliner.
Posted: Wednesday, May 20, 2009 link to this item, respond to this item
Breaking old new ground
I think there's a lot of value in looking back at past cutting-edge documentation to understand how far our techniques have come, or not, as the case may be. Back in 1987 computer-based illustration was new, as were the user interface conventions we now take for granted. In the instructional video Meet Adobe Illustrator computer users were introduced to many new concepts. Part instruction, part marketing, the video is an interesting reminder of a recent, but technologically distant, past.
See also: Listen To How Far We've Come.
Posted: Tuesday, May 19, 2009 link to this item, respond to this item
Remembering steps
Brett McLauglin, in Your Brain Really is Forgetting...a Lot for O'Reilly Radar discusses a little cognitive science that's of interest to instructional designers. In brief, it's believed that when a person retrieves a memory, the memory is "re-written" with a new context.
One implication for documentation is that the common practice of repeating standard steps, such as opening a preference dialog box, might impact how these steps are recalled later. For example, if the instructions teach the user that a particular setting is in Preferences, and then later the user learns that another setting is in Preferences, are the steps for accessing the preferences dialog reinforced, or are they seen, cognitively speaking, as distinct for each context?
While there is certainly a stylistic difference between linking to common tasks and repeating common tasks throughout the document, does the cognitive difference have a meaningful impact the reader's ability to learn (as opposed to perform) the procedure? Food for thought.
Posted: Thursday, May 7, 2009 link to this item, respond to this item
Are games the last basion of documentation?
Industry old timers remember when software products came with a thick printed manual, sometimes an entire suite of documentation, and the rare exception might be a game or educational product aimed at those too young to read. But today the situation is quite different. The most complicated of application might come with a brief "Getting Started" booklet, with the rest of the documentation provided onscreen or online.
Yet somehow, games have managed to hang on to, if not grow, their printed materials. In a response to a reader's letter to Nintendo Power magazine praising one game's documentation, the Editors responded: "There's something really satisfying about cracking open a game case to find a thick, well-designed, colorful manual. [...] Little details like those help a game feel like a quality experience."
So if you're longing for the days of books cozy up with a new game, you might just be surprised at what you find inside the box.
Posted: Sunday, May 3, 2009 link to this item, respond to this item
Contributory contradictions
Allowing readers to supplement your documentation with comments or additions is an appealing prospect, as discussed in An Example of User-Supplemented Help, but it also opens the door to off topic, if not inane or offensive, additions that might escape immediate notice.
In Internet Comments as Heckling you'll find a reasoned argument about how website comments seem to bring out the worst in people, with concrete examples that will be familiar in tone to most anyone.
Dealing with these issues will need to be a first priority for any documentation system that allows others to add their unfettered perspective.
Posted: Friday, April 17, 2009 link to this item, respond to this item
The price of free documentation
Lauren Weinstein, a privacy and Internet advocate, writes a provocative essay about the decline of newspapers in the Internet age. But the essay is also about how advertiser-supported content is at risk, which is where it most obviously intersects with the interests of technical writers. As fourth-party documentation sites continue to appear, is their revenue model any more secure than that of newspapers?
See also Fourth-party Documentation and Additional Developments in Fourth-Party Publications.
Posted: Sunday, April 12, 2009 link to this item, respond to this item
PopSci's interactive magazine
Popular Science is countering the proliferation of documentation for dumb people with their new Genius Guide series. The first of the quarterly issues focuses on home entertainment systems. I contributed an article on do-it-yourself automation of a home theatre system.
PopSci is using the Zinio e-magazine platform for this project, but they're approaching it in a unique way. Usually Zinio publications are electronic versions of printed magazines and are page-for-page identical to their printed counterparts. But not the Genius Guides. They're only available in Zinio format and the publishers have added lots of interactivity and every page is designed for widescreen viewing. As a result many of the constraints of paper publishing have been avoided, although the Zinio platform still maintains some vestiges of its magazine heritage. With an introductory price of just 99 cents the first Genius Guide is an inexpensive way to see how one publisher is trying new approaches to traditional publishing. For a peek and discussion, see Stop the Presses on the PopSci blog.
For more about my contribution, see The Remote-Control Living Room on my personal blog.
Posted: Saturday, March 28, 2009 link to this item, respond to this item
MacSnapper, a documentation tool
MacSnapper is a tool that simplifies the creation of step-by-step task documentation in PDF or HTML format. One unique feature is its ability to upload your documentation directly onto a WordPress blog. For an example of the instructional approach it supports, see the MacSnapper documentation which was created with the tool.
See also the discussion of ScreenSteps in Updated Job Aid Creation Tool.
Posted: Saturday, March 28, 2009 link to this item, respond to this item