Examining documentation and help systems since 2002
Contents
Special Reports
Subscription Feed
Gordon R. Meyer
Copyright 2002-2012
Favorite Sites
Grammar Girl's Quick and Dirty Tips for Better Writing
Holding tech journalism to a higher standard
Hunter Walk writes about the state of technical journalism and its tendency to favor the echo chamber of product rumors, rehashed press releases, and reader comment baiting. It's an interesting look at the pressures and reality of technical writing beyond the world of instruction manuals.
Posted: February 11, 2012 link to this item, Tweet this item, respond to this item
If computers had warning lights
Why the Check Engine Light Must Be Banned, at Jalopnik, argues that automobiles should be more informative about their error conditions. The problem, they say, is that the light provides no detail at all, it simply tells you that something is wrong and you should have the car checked.
What if computers worked the same way as cars do today? Instead of horribly obtuse and technical error dialogs, you'd just be told to take your computer to the Genius Bar or Best Buy (heaven help you). I have to admit, I like that idea a lot. Imagine a world where you are never subjected to messages about things you can neither fix nor act upon. No more mindlessly clicking OK. If computers only alerted you to fatal conditions, it would completely change the computing experience.
(Creative Commons screenshot from Flickr user Sandy Kemsley)
I know that's the opposite of Jalopnik's argument. But really, unless you're a gear head, most of the error messages your car would show you are going to be as scary and unfathomable as those that you get from your computer. The only problem with the Check Engine light as I see it is that there's no clear sense of urgency about the condition. For example, I once I had Geo Tracker. The instant the odometer rolled over to 50,000 miles, the Check Engine light turned on. Nothing was wrong, it just needed a milestone checkup. That damn light scared the heck out of me when it illuminated (for the first time ever since I bought the car) during a snowy rush hour drive on the Tri-State Tollway. I was quite irritated to later find out why it came on when I took it to the mechanic.
Back in the day, Macintosh provided for different types of alert messages. Alerts that were informational featured a speech bubble, while more important errors had a bomb. Today, desktop computers more often exclaim urgency and demand attention for the tiniest of matters.
(Lovingly designed by Susan Kare.)
So it's probably unlikely that we'd collectively have the discipline to only turn the Check Engine light on when it really mattered. But as computers become more like appliances, I can dream.
Posted: February 5, 2012 link to this item, Tweet this item, respond to this item
Does gender matter when it comes to Help?
Writers UA features Leah Guren's study of Cultural Dimensions of Software Help Usage. It's a fascinating report, particularly the observations about the perils of deep hierarchy and user's inattentional blindness.
Posted: February 2, 2012 link to this item, Tweet this item, respond to this item
Read the Help, increase your score
The fun and very attractive iOS game Astronut features a unique "achievement." Players earn 5 points if they "scroll through" all of the app's help. Apparently there's no extra bonus for actually reading it.
Posted: January 29, 2012 link to this item, Tweet this item, respond to this item
Learning from old examples
Sure it's geeky, but it's fun and educational to study instructional materials from the past. You can see how much (or how little) has changed in our profession, and pine for overproduced pieces. Here are two you might enjoy. A 1923 silent film that explains Einstein's greatest work (Vimeo link) and an operator's manual for the Disneyland Monorail (PDF link).
See also Old Disney Manuals and Playboy Club Bunny Manual.
Posted: January 22, 2012 link to this item, Tweet this item, respond to this item
Android basics for writers
Google has released guidelines for designing Android applications. The site is lovely, and there are two sections of particular interest to technical writers. Writing Style provides six guidelines for brief and friendly onscreen text. Gestures provides standardized descriptions and names for user actions.
See also: Apple Publications Style Guide updated
Posted: January 15, 2012 link to this item, Tweet this item, respond to this item
Writers UA approaches
The annual Writers UA Conference is being held in Memphis, TN in March of this year, and the early registration deadline is rapidly approaching. I've attended and presented several times over the last few years, and I'm always impressed with the event. I find it more technically adept than many technical meetings (yes, there's a bit of irony there) and very well organized.
See also: A Look at Developing User Assistance for Mobile Apps
Posted: January 12, 2012 link to this item, Tweet this item, respond to this item
Can documentation be "social?"
A press release from the folks at Mindtouch raises some interesting questions about internal processes for creating online documentation. I'm not familiar with this particular product, but the premise is that everyone in a company, not just technical writers, can directly contribute to a product's documentation. Frankly, I found their site laden with corporate gobblygook, but the question of how to efficiently use the expertise found across your company to improve user documentation is worthy of a great amount of thought.
Posted: December 15, 2011 link to this item, Tweet this item, respond to this item
Touch, Tap, Hold.
Documenting touch-based interfaces introduces a whole new set of writing and visual design challenges. Konigi's Touch Gesture Notation provides links to several different attempts at solving the problems.
Thanks to @mattgemmell for the tip.
Posted: December 13, 2011 link to this item, Tweet this item, respond to this item
To link or not to link
As discussed at A New Kind of Book, hyperlinks are often cited as one of the main advantages of onscreen publications. I have long thought (see below) that they can be overly distracting, and this article identifies several additional types of potential pitfalls.
See also: Stop Linking, Embed Instead and Linked to Distraction.
Posted: December 8, 2011 link to this item, Tweet this item, respond to this item
Measuring your FAQ
I'm not a big fan of the "Frequently Asked Questions" approach to documentation. But if you have to create one for your product, take a look at the FAQme service. Their clean design avoids information overload. Additionally, they promise to provide you with usage statistics, which might lead you to discover just how infrequent some of your FAQs really are.
See also: The Rise of the FAQ, and The Siren Call of a FAQ.
Posted: December 2, 2011 link to this item, Tweet this item, respond to this item
Tricky interactive tutorials
One of the biggest challenges for any interactive tutorial is keeping the reader on the path you've defined. The software is typically operating in a "sandbox" environment, and is programmed to respond to specific user actions. If the reader decides to deviate from the tutorial, or gets too confused, the whole thing can easily fall apart. Careful planning and thought about remediation is a big part of the instructional design for any tutorial project.
The Try Ruby tutorial is a fun and interesting example. It gets several thing right, including the up-front statement of how much time the reader will be investing. It's worth spending 15 minutes to try it out, even if you're not interested in programming.
Posted: December 1, 2011 link to this item, Tweet this item, respond to this item