by Scott Nesbitt

Balloon help: a short history  Clip to Evernote

We tend to take embedded assistance like tooltips for granted. But where did tooltips come from?

From an Apple, if that surprises anyone. From 1991 to 2001, Mac OS incoporated something called balloon help. This Wikipedia article looks at the history of balloon help. It was and interesting idea, and was more detailed than the tooltips that we’re used to, but balloon help still didn’t take up much screen real estate.

What’s interesting is that Apple set standards for the wording of balloon help:

Developers were encouraged to include help text with a certain grammar, and not only name the object being looked at, but also explain to the user any state it might have. For instance, modern tooltips might say something like “copy” to explain a button, but Apple suggested the more detailed “Copies the selected text onto the clipboard,” as well as a second version that added “Not available now because there is no selection.” This sophisticated feature was invaluable for someone trying to understand why a particular menu item was greyed out. In this respect, balloons were far more helpful than modern tooltip systems, and helped users learn more about how their applications worked.

by Scott Nesbitt

Developing knowledge base articles  Clip to Evernote

One great, and often overlooked, sources of user information is a corporate knowledge base (often shortened to KB). Whether used internally or externally, the KB combines user-generated (or, at least, user suggested) documentation with more technical material. But don’t think that the content in a KB is for techies only — it can, and should, cater to users of all skill levels. Continue reading →

by Scott Nesbitt

Advice on writing captions  Clip to Evernote

When you think of captions, what comes to mind are probably pithy sentences below (or above) photos in print or on the Web. Or, maybe, text for the hearing impaired on TV.

But the ability to write good captions is a useful skill for any technical communicator. If you include illustrations or figures in your documentation, a short but descriptive caption is a must. All too often, though, captions are pretty lame: Figure 3: Exploded view or some such. I’ve been guilty of that in the past.

Any technical communicator can learn a lot about writing captions from a newspaper or magazine copy editor. Unfortunately, most of us don’t have ready access to one. But this blog post offers nine bits of advice for writing strong captions. Some of the advice (like points 3, 6, and 7) doesn’t have that much relation to technical communication but you can definitely learn something from the other points.

by Scott Nesbitt

Going from wiki to online help  Clip to Evernote

I probably don’t have to tell you that wikis are gaining traction as an environment for authoring and even publishing documentation of all sorts. Of course, there are many technical publications teams that need to get the content out of a wiki and into, say, online help or a PDF. There are a few solutions for that — including the one that the folks behind WebWorks are putting together.

The other day, I stumbled across this blog post. It outlines how the author got the content out of MediaWiki and used it to create an Apple Help system.

Most of the work was done on the command line using tools like wget, HTML Tidy, and Perl. The post is an interesting read, and shows how with a little ingenuity you can expand the possibilities of using a wiki for documentation.

by Scott Nesbitt

It’s not the tool, it’s the writer  Clip to Evernote

The tool is not important. I remember reading those words at Gordon McLean’s blog and nodding in silent agreement. I think that technical communicators can put too much of their focus on tools and technologies at times — sometimes because of the promise of those tools and technologies, and sometimes just to to embrace our inner geeks.

But, as Gordon said, the tool is not important. At least, not to the users of the documentation that we produce. A person reading a help file doesn’t care if it was generated from FrameMaker sources using WebWorks or from a Word file using RoboHelp. All they want is for the content to be useful. Continue reading →