Examining documentation and help systems since 2002.
Contents
Special Reports
Subscription Feed
Gordon R. Meyer
Copyright 2002-2010
The technology of cooking
Cookbooks are often overlooked by instructional designers as a source of inspiration, but cookbooks are perhaps the most successful consumer-level technical documentation ever produced. As evidenced by the fact that most people don't even regard them as "documentation," and by their sheer number and ubiquity in the home.
The Atlantic writes, in Recipes of the Nerds, about a new book that embraces kitchen and food skills as science--Cooking for Geeks.
The book has been a big hit for O'Reilly (disclaimer: they're my publisher too) and aside from the practicality of the tome, it's worth a peek for its instructional approach.
See also Cooking Without Jargon, Do Cookbooks Teach You How to Cook? and Cooking Up Help.
Posted: September 6, 2010 link to this item, respond to this item
Visual Touch-ography
In Touch Notation, Matt Legend Gemmell proposes a method for graphically describing a touch-based gesture, such as those used on iOS devices like iPhone and iPad. The proposals for simple gestures, such as rotating or swiping, seem clear enough but some of them feel more like charades then instructions, in my opinion.
Gemmell's proposal is for in-house development shorthand, so there's no need to eschew a more standard illustration or--heaven forbid-- actual words in your documentation. But stil, it's an interesting things to think about.
Posted: August 18, 2010 link to this item, respond to this item
The forgotten, yet passionate, middle
Mark Bernstein's essay Unreasonable argues, among other things, that our culture perpetuates the belief that software professionals are idiot savants, and that users are simple minded children who shouldn't have to think when they sit down in front of a computer. As a result, there is little room in the market for intelligent discussion of deep software products.
His observation strikes me as true, and I think it also applies to the domain of product documentation and help systems. Instructional designers always work with an audience in mind, but that "ideal type" rarely includes the broad middle range of intermediate users.
Here's a fun exercise to try: Take a manual for a product that you know well and markup each section with who you think the writer is addressing--beginners, intermediate, or advanced users. Then calculate the percentage of the book dedicated to each type of audience. If there is a gap in the middle, as there often is, ask yourself if the documentation is truly serving the product's best interests. Expert information in a beginner's manual befuddles new users. Manuals that are too dumbed down infuriate the experts. Those who somehow manage to graduate from being newbies? Well, I guess they'll figure it out.
Posted: August 12, 2010 link to this item, respond to this item
Linked to distraction
Nicholas Carr, writing Experiments in Delinkification for Rough Type reports on the problems associated with articles that are excessively hyperlinked. In brief, they're distracting, require cognitive energy, and discourage attention and comprehension. One solution is to offer the links at the end of an article, instead of embedded throughout.
Posted: August 6, 2010 link to this item, respond to this item
Basil Wolverton's instructional design
Comic artist Basil Wolverton's series, Whiz Comics, ran from 1945 to 1952 and featured a large number of "how to" topics. Clearly humorous, but also great fun from an instructional design perspective. The Dinosaur Gardens website has a fine collection to peruse.
Posted: July 15, 2010 link to this item, respond to this item
When the going gets tough
if your career in technical writing has you down, perhaps you should consider calling yourself an information architect instead. That's not exactly the point of Klariti's article, How to Get Out of Technical Writing and Make More Money, but in my analysis that's the bottom line. Of the suggested career changes, most are just synonymous positions. But hey, maybe "sanitation engineers" really do make more than "janitors."
See also: A Rose By Any Other Name and Technologists Need Not Apply.
Posted: June 19, 2010 link to this item, respond to this item
Interactive Word command reference
Microsoft has an interesting command reference tool for users switching from Word 2003 to Word 2007. It mimics the Word interface and, as you choose commands, shows and tells you where the command is located in the new interface. This takes advantage of the users spatial and visual memory for frequently-used commands, but it strikes me as overly comprehensive--a common tech writing mistake--because it also includes commands that have not changed between the versions. In that scenario, it seems unlikely that a user would refer to this tool at all.
Posted: June 16, 2010 link to this item, respond to this item
Written by committee
The Ubuntu Manual Project offers a free PDF of a getting started guide for the free operating system. The 160 page document purports to be jargon-free and has been written by a group of 21 writers and editors, plus a very large extended team.
Posted: June 15, 2010 link to this item, respond to this item
Authoring Apple Help with Texinfo
Michael McCracken describes the process of creating Apple Help, HTML, and PDF from a single source base using Texinfo.
Posted: May 27, 2010 link to this item, respond to this item
Firefox attempts humor
Humor in technical writing and UI design is a very tricky thing, and a thematic topic over the years here at Usable Help. A recent error dialog from Firefox seems to strike a nice balance if you were to consider such an approach necessary.
See also Web 2.0 and Humor and The Crabby Office Lady Offers Help.
Posted: May 19, 2010 link to this item, respond to this item
Teach them to fish
Teachers have long held that instead of instructing students how to do a specific task, a more viable strategy is to teach how to find and utilize information. The web comic xkcd brings the point home with this edition, which could eliminate a large portion of user documentation if its adoption becomes too widespread.
Posted: May 19, 2010 link to this item, respond to this item
Complexity as a form of job security
UX Magazine, in The Impossible Bloomberg Makeover, discusses the odd, but real, case where users resist efforts to improve a system because it threatens their mastery of the difficult.
I'm reminded of cases where writers resist simpler documentation because creating complex, lengthy manuals demonstrates that the product is too complex to be documented in any other fashion. Yes, that's an actual, but circular, argument.
Posted: May 3, 2010 link to this item, respond to this item