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
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, 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, 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, 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, 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, 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, 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, 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, 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, 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, respond to this item
The upside of Twitter and documentation
A story at the NYT Learning Network describes how the "social media" writing style can be exploited to encourage concise student writing. Could we be so lucky that the same thing happens to user documentation?
See also: Tweeting a book, bit by bit.
Posted: November 15, 2011 link to this item, respond to this item
Rethinking text and illustration
A New Kind of Book discusses the fantastic work of fiction, The Invention of Hugo Cabret. Its use of illustrations is quite intriguing and unique, and as the discussion suggests, it raises questions about how text and illustrations are often presented. Read the discusson from an instructional design perspective, and you might rethink how you approach screenshots in your manuals.
Posted: November 6, 2011 link to this item, respond to this item