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.

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

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?

Posted: March 9, 2014 link to this item, Tweet this item, respond to this item

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.

Posted: March 2, 2014 link to this item, Tweet this item, respond to this item

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.

See also: From 1984, Listen to How Far We've Come, and Apple's First Manual.

Posted: February 18, 2014 link to this item, Tweet this item, respond to this item

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

Posted: January 19, 2014 link to this item, Tweet this item, respond to this item

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.

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

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.

Posted: December 7, 2013 link to this item, Tweet this item, respond to this item

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.

Posted: December 2, 2013 link to this item, Tweet this item, respond to this item

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.

Posted: November 29, 2013 link to this item, Tweet this item, respond to this item

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.

Posted: October 11, 2013 link to this item, Tweet this item, respond to this item

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.

See also: Basil Wolverton's Instructional Design, Learning Instructional Design From a Master Artist, and Comic Art and Technical Information.

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

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

Posted: August 25, 2013 link to this item, Tweet this item, respond to this item