Writing to avoid trunca...

There's no surer sign of a sloppy engineer, and perhaps a tech writer sleepwalking through their job, then a UI string that doesn't fit in its allocated space. The anonymous example below is a good one. Detect End-of-What, exactly?

Posted: May 19, 2013 link to this item, Tweet this item, respond to this item

Apple Style Guide 2013 released

Apple's in-house style guide, last publicly updated in 2009, is now available in a 2013 edition. Previously called "Apple Publications Style Guide," the introduction says the book has been renamed to reflect non-printed deliverables. It's available in PDF and browsable HTML.

See also: Justifying a Style Guide

Posted: May 12, 2013 link to this item, Tweet this item, respond to this item

Is text-speak really teh sux0r?

John McWhorter, a linguist, has a great TED Talk on the subject of "texting grammar" and how it compares to the traditional written word. It's easy to dismiss the evolving style, but McWorter's perspective just might change your mind. And we all know that technical writing is a bastion of old-school style.

The talk, "Txtng is killing language. JK!!!," is discussed (and embedded) at John August's Writing vs. Speaking.

Posted: May 5, 2013 link to this item, Tweet this item, respond to this item

The novelty of actually reading the manual

The Internet is awash in advice about how to increase your productivity, but there's one tip that is such common sense it is often left unsaid. Namely, read a product's manual. Even if you've been using a product for a while, and consider yourself an experienced user, there is likely still something to learn by skimming the doc. That's the premise of Victor Agreda, Jr's Productivity Tip.

Agreda links to The Manual--And Why We Don't Read It, and it's also worth perusing. Gary Hoffman argues that manuals are too often written for "blithering idiots" and, he says, learning how to do something would spoil the fun of figuring out how to do it yourself.

Posted: April 28, 2013 link to this item, Tweet this item, respond to this item

Justifying a style guide

Patrick Cox writes Do I Really Need a Style Guide? While it's focused on web style guides, the rationale it provides applies to documentation style guides, too.

See also: Developing a Useful Style Guide

Posted: April 21, 2013 link to this item, Tweet this item, respond to this item

Usable Help on Flipboard

If you're a Flipboard user, and want to receive Usable Help using that fine app, you can subscribe to the new Usable Help on Flipboard magazine. All future posts will appear there automatically. Thanks in advance.

Will Flipboard's magazine platform succeed? Beats me. But Paul Armstrong thinks it's a big deal. It's certainly interesting, at the very least.

Posted: April 15, 2013 link to this item, Tweet this item, respond to this item

Wabi-sabi and Minimalism

As an avowed minimalist, I often encounter people who think that it represents doing less and omitting important things. But that's a negative way of viewing what it's really about---providing only what's truly necessary. Similarly, the Japanese philosophy of Wabi-sabi focuses on keeping things clean and unencumbered, but not removing their essence.

One challenge of minimalist documentation is that it requires careful and attentive reading. The usual cruft of 'blah blah blah" has been omitted, but readers encounter "comprehensive" documentation so often that they've been trained to skim and skip over bloated descriptions. When there's no fat to skip, readers can miss important info.

The discussion about Wabi-sabi's simplicity at 37 Signals is instructive about the challenge of maintaining, but not emphasizing, importance.

Posted: March 31, 2013 link to this item, Tweet this item, respond to this item

Just-In-Time Help

Edward Tufte's website has a fun discussion about Instructions at the Point of Need. A concept that is related to, but not as fancy as, contextual help.

For my own contribution, here's a photo of what a Panasonic projector shows when there is no video source connected to its input. The screen describes how to activate a laptop's video-out functon.

Posted: March 31, 2013 link to this item, Tweet this item, respond to this item

Self-identifying audiences

It's a real challenge to write a single set of documentation for readers with differing amounts of expertise. If you assume too much beginning users will be lost or--worse yet--get in over their heads. And of course if you cater to the newbies, advanced users will ignore your documentation, even though they might stand to learn something if they'd only stick with it.

One solution is to have users self-identify their ability, although if done too broadly, I don't thinks this works very well. None of us is very good at assessing ourselves, particularly when using a measurement of unclear scope and calibration.

Google's new Webmasters Help for Hacked Sites takes an interesting approach. The overall document is written for all users, but certain steps are identified as being for "advanced, intermediate, or beginner" users. One thing this communicates is that there are some things that everyone can do, a few that a lot of people can do, and a couple that require expertise. This lets readers know at a glance if they're ultimately going to be able to solve the problem by themselves.

Posted: March 23, 2013 link to this item, Tweet this item, respond to this item

A resource for GUI history

After 40 years of development, the graphical user interface has a rich history. Many applications today just re-invent, or re-implement, ideas that have already been explored and established. Before you're convinced that you are breaking new ground, it's a good idea to check the GUIdebook for a glimpse at the work of those who have come before you. If nothing else, it's a nice nostalgia trip, too.

And don't miss the overview of help systems. It would be a shame for me not to mention the Gallery of Onscreen Help too, I suppose.

Posted: March 17, 2013 link to this item, Tweet this item, respond to this item

Evolution of Roomba's Virtual Wall instructions

In the not too distant past, I was in love with the Roomba line of household cleaning robots. Over the course of buying several different models, I noticed an instructional evolution taking place, in regards to the on-device help for positioning their Virtual Walls. (A virtual wall uses IR to tell the robot to avoid a certain area.)

It's easy to imagine a narrative for the changing approach. The first model of virtual wall, shown on the left, did not have any built-in documentation. Customers probably weren't looking at the printed manual, so for the 2nd generation (middle) they added usage instructions. It's a beautiful diagram, but it's wordy and detailed. For the 3rd generation, the instructions are simplified and wordless, which allows the product to be sold and used worldwide. Notice too that they're now a part of the door, instead of being printed on the door, which saves a manufacturing step.

Posted: February 24, 2013 link to this item, Tweet this item, respond to this item

A lightweight way to track changes

Lightweight text-only markup tools, such as the popular Markdown, have great promise for a solo or small team of writers. However, using text-based tools usually means giving up some niceties, such as detailed change tracking. CriticMarkup is a fascinating new approach to solving that problem. Your Editor or collaborators indicate their changes using a set of simple notations, then you can render the file to a familiar visual display of strikeouts, inserts, and comments. There's even an option to "accept changes" when you're finished.

If you're a Mac user, also check out Fletcher Penney's excellent MultiMarkdown Composer app, which recently integrated CriticMarkup support.

Posted: February 17, 2013 link to this item, Tweet this item, respond to this item