Reading Usable Help
@UsableHelp on Twitter
Gordon R. Meyer
Not our job to make it easy
Mark Bernstein, writing Intuitive, argues that professional software doesn't always have to always make things intuitive because it makes things possible. It's a short, stimulating perspective by someone who does the real work. (Bernstein is the creator of Tinderbox, the software I've been using for over a dozen years to create this website.)
I generally agree with what Mark is stating, as not every tool should be reduced to the simplest, monkey-proof set of options. Easy and intuitive are fine goals and should almost always be measures of success, but that doesn't mean a product has to be intuitive for every type of user. It's OK for a tool to be written for people who know what they are doing and what they want to accomplish.
Documentation faces a similar challenge that is, perhaps, even more pronounced. It's very common for writers and reviewers to want the instructions written for "the grandmother who just bought her first computer," or the person who, apparently, has no motivation or reason to be using the software in the first place.
How to make a design problem worse with documentation
About a year ago I wrote about my experience using an Energizer flashlight that would automatically turn itself off after a few seconds of use. The short version of the story is that it is caused by a demonstration mode that that is poorly described in the documentation. (Yes, a flashlight with documentation, go figure.)
Well, despite the problems, I really liked the "Light Fusion Technology" that the flashlight used, so I decided to buy another model in the same product line. The new model also had the same, crazy demo feature. But instead of a user guide, this time they affixed a sticker to the unit, apparently hoping to explain the reset procedure.
Unfortunately, the sticker is just as bad, if not worse, than the user manual was. While it is more discoverable for certain, the wording continues to obtusely refer to the problem and solution. So now you have a big, ugly, multi-lingual warning that tells you nothing about why the flashlight will not stay turned on.
By the way, this time I returned the flashlight to Amazon. As noted by other reviewers, the battery door is not affixed very securely, and I was put off by the fact that Energizer--a battery company of course--sells the light without a complete set of batteries. "Batteries Not Included," indeed.
Managing prose as if it were code
Frank Miller, writing Is Managing Content the Same as Managing Code? for CIDM, offers several important points on the pitfalls of writers using version management systems that have been designed for programmers. Yes, it can be done (as many shops will attest), but it's not very efficient or effective. Those who contend that "words are just bits" don't really understand what productive writers need.
Tech writing with heart
James Somers, writing You’re Probably Using the Wrong Dictionary, observes that somewhere along the line our dictionaries were drained of life and nuance. It's a great article and anyone who loves words will enjoy it.
Far be it from me to commit the heresy of suggesting that technical writing should be engaging, but I can't help observing that most software documentation is in a very similar situation.
Walkthroughs are cruft to be scraped away
Sarah Perez, writing Rethinking the Mobile App “Walkthrough” for TechCrunch wonders if introductory UI walkthroughs are going too far. (And in the time since the article was written their usage has only increased.) Perez cogently raises some important questions to consider, including the impression of complexity that's created, the barrier they create for new users, and their overall lack of good (or any) instructional design. My favorite bit is the characterization that they are cruft that the user has to scrape out of the way. My view is that the biggest problem is that they appear at exactly the wrong time in the learning-cycle.
A thousand words in a jiffy
David Smith, author of the RSS tool Feed Wrangler, writes about his methods and workflow for creating animated GIF files to supplement documentation. Although the example given is not very compelling from an instructional viewpoint, the Mac-based writer will find his tips useful
Generate good faked data
Here is yet another method to create faux information for use in screenshots and examples. Faker is a Python-based program that can generate almost anything you'll need, in a variety of formats. Although designed mostly for testing, technical writers will probably find it useful, once the technical challenges have been overcome.
See also: When you need fake user data
Optimizing for simple
Cartoonist Scott Adams writes about how some people are simplifiers, and some are optimizers. Simplifiers look for the easiest way to complete a task, while the other group puts in more effort for a better outcome. Adams points out that when it comes to communications, simplification is the way to go. But, I'll add that some documentation takes the opposite approach in the name of being comprehensive, or perhaps purposefully crafted to demonstrate certain features or options. If your documentation isn't presenting each task in the simplest way possible, then exactly whom is it trying to serve? It might be time to focus on the customer instead.
Title goes here
The website What Happens When Placeholder Text Doesn’t Get Replaced is the stuff that keeps tech writers awake at night. Who among us hasn't had this nightmare?
An impressive online tutorial
The Portland-based software company Panic Inc has posted an amazing web-based tutorial for its Diet Coda web development app for iPad. Click the "Try Diet Coda Right Here, Right Now!" button at their site and enjoy a free-form tutorial that simulates the app, teaches its features, and includes a healthy dose of voiced-over humor. (Which can be turned off if you're in a serious mood.) It's an impressive piece of web programming (no plug-ins required) and instructional design. (And as a Diet Coda user, I can attest that the app is good, too.)
To see how far we've come contrast this to the last week's item about the 30 year old tutorial for the original Mac.
Thirty years of Macintosh
It has been 30 years since Apple introduced Macintosh and its impact on personal computing is undeniable. The user interface that it both mainstreamed and pioneered was utterly new to the consumer market and required thoughtful instructional design. Each new Mac shipped with a Guided Tour that utilized onscreen and spoken tutorials, the latter played from a casette tape. Revisit what is was like by watching at least part of the tour on YouTube and you'll see how far we have, and haven't, come in the last three decades.
Another horse in the XML race
The "oManual" (Open Manual) specification is an interesting development that's worth keeping an eye on, although I didn't find it sufficient for my own work. It is a far measure more simple than DITA, which is a plus, and it has O'Reilly Media as one of the founding contributors. (O'Reilly is my publisher.) Perhaps its most interesting feature is that it is both a schema and an API, which could allow onscreen manuals to finally become a lot smarter.
On the downside, probably due to its origins with iFixit, it is heavily biased towards repair and assembly procedures. It also has some in-built appearance controls, which is surprising in this culture that insists on complete separation of "content" and format.
it appears the only big client so far is the Dozuki hosted wiki, based on the project's website, but the unfortunate side effect of the name is that it's difficult to search for other sites with more to say about it.
See also: Dozuki Wants to Host Your Manuals