Reading Usable Help
@UsableHelp on Twitter
Gordon R. Meyer
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
Watching the readers
The New York Times, in As New Services Track Habits, the E-Books Are Reading You , describes how book subscription services can provide very deep metrics about how readers interact with books. As product documentation has moved online, technical writers get some information about what is being used by customers, but this sort of insight would be fascinating, if not disheartening at times.
I'm an Oyster subscriber, by the way, and I'm really pleased with the service despite the breadcrumbs I'm apparently leaving behind.
Don't tell me you love me
The iOS app Ember is called out for its unique approach to gathering user feedback. An in-app survey asks for the user's opinion on the app. If they indicate they love it, they're invited to post or tweet about their affection. If they indicate that they find the app confusing, they're directed to RTFM. Or, if they're unhappy, they can send off a poison pen letter via email. Spread the love, indeed.
Are we not men?
Bryan Cantrill, CEO of Joyent, writes about how using gender-specific pronouns in code comments is a firing offense. Is your documentation also gender-neutral? Cantrill's article is well worth reading, as is the train wreck of comments around the issue.
Books aren't dead yet
A recent survey by Voxburner found that 62% of people between 16 and 24 years of age prefer printed books over ebooks. Speculating as to the cause, it may be because physical books are better designed, imbued with some prestige, and offer a better browsing and discovering experience. Frankly, I'm skeptical, and I doubt the fondness carries over to the mundane user guide, but nonetheless there might be some life in the printed word yet.
Simplified iOS 7 screen shots
The OS X utility Status Magic allows you to easily customize the status bar shown in iOS screen shots. This can be very useful for cleaning up unnecessary or distracting icons, such as Bluetooth, battery, and carrier information. It can also be used to harmonize the time shown at the top of every screen. The website Mac Stories has a nice overview.
A stick figure explains cryptography
Jeff Moser, an Indiana-based software engineer, has created A Stick Figure Guide to the Advanced Encryption Standard (AES). Presented in four acts, it progresses from an everyman description of cryptography to a detailed discussion of the math involved. I particularly enjoyed the well-timed exit of portions of the audience as a way of indicating the increasing degree of specialization behing presented.
Linking: All things in moderation
Gerry McGovern, writing No Link Is an Island: The Problem With Silos on the Web for CIDM, makes the argument that "silos of information" result in confusing navigation and hard-to-find documentation.
McGovern's advice makes sense, but the nature of silos is that you don't have control over your neighbors. So unless you're able to coordinate exceptionally well, sometimes pretending that other sites don't exist is the only way to bring structure and order to your own. It's one of the biggest challenges for technical documentation on the web, I'm sure we'd agree.
See also: To Link or Not to Link
The unspoken meaning of punctuation
UI writers and editors have endless debates about such practices. Many will argue that full sentences must be correctly punctuated. Others are emphatic that tool tips should almost always be sentence fragments. Scrivener is a great app, I use it myself, and after seeing this tweet I explored its many, many Help Tags. The implementation is generally very good (except for that full sentence thing in some cases), and what's going on here, I think, is the bane of Consistency. All the other Help Tags have periods and so must these, even when the tag is only being used to provide a name for an unlabeled control.
Documentation that drains willpower
A must-read article, Your App Makes Me Fat — Serious Pony, describes how cognitive taxation affects willpower. Although primarily a plea for simpler to use apps, the same logic applies to documentation, too. If the tenet that documentation is used only as a last resort is true, then your readers are already drained when they come to what you've written. Will your complex help system and overly-long instructions bleed the last of their rational mind, or will it solve their problem so they can recharge?