ffeathers — a technical writer’s blog

This is a special edition of the ffeathers blog, to report the spectacular growth of my Prickly Paperbark tree since I last blogged about it approximately a month ago.

On 13 April, the tree was 172 cm. Today it’s 188 cm — grown 16 cm in five weeks! It’s now over 6 foot and taller than I am. I planted it in August last year, so it’s about nine months old.

Alas, it’s not only the Paperbark that has been growing. I spent a couple of hours this morning removing the Asthma Weed and Wandering Dew that had draped themselves all over the tree and its neighbourhood. Don’t gardens ever take a rest period in Sydney?

Just to reassure anyone who might be concerned about the Old Man Banksia I planted at the same time as the Paperbark: It’s doing fine too. It hasn’t grown so spectacularly since my last post a month ago, so it doesn’t warrant a special edition

Here’s a closeup of the trunk, with a peg for perspective:

This week I attended the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. The last session was entitled “The World’s Word Error Messages, or How to Scare End Users” presented by Frank “Choco” Munday.

Choco is a prolific and experienced technical writer, author and adventurer, and a member of the Australian Federal Police. He has collected a very amusing set of real-life error messages to illustrate and enliven the sound principles behind his talk — how to review and write good error messages.

The serious stuff

Software developers have to write text that is more important than any other text in the application or documentation: the labels etc on the UI and the error messages. It’s up to us, as technical writers, to review their work. Choco has “trained” his developers to consult him whenever they need to write something.

A good error message:

• Is polite and doesn’t blame the user.
• Clearly describes what’s wrong.
• Gives advice on how to fix it.
• Is in a human-readable language.
• Gives an indication of the severity of the problem.
• Does not include hostile words like “abort”, “kill”, “invalid”, “illegal”.
• Is targeted towards the user not the developer.

Some less-than-ideal error messages

All of these error messages are real i.e. they do or did appear in an operating system or application:

• “When casting from a number, the value must be a number less than infinity.”
• “Error: The operation completed successfully.”
• “Your mouse has moved. Windows must be restarted for the change to take effect.” This one is from the early days of the USB mouse in Windows 98 and now appears on t-shirts.
• “Value Error: insecure string pickle.” This comes from PaintShop Pro and has something to do with pickles in Python, the language used to create PaintShop Pro.
• “Please kill your PC!” From Nero.
• “Stop that!” From IE beta in early days of XML parser.
• “Press any key to continue or any other key to quit.” From Microsoft Exchange.
• “The command has been aborted. An internal error occured in Pro/DESKTOP. It is most likely that doing the same thing again will produce the same error.”

And lots more.

My conclusions

Choco, we are forever in your debt. This session was just perfect to for a Friday afternoon. Choco had us wiping away tears of laughter while getting the message (get it ) at the same time.

This week I attended the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. In one of Friday’s sessions, Matthew Ellison explained the concept of “guided help” and showed us some fascinating examples. His session was entitled “Guided Help: A Revolution for Software Help and Support?”

Matthew is a user-assistance professional who runs his own company, Matthew Ellison Consulting. He started his talk with sandy feet (The conference was in Surfers Paradise, three minutes’ walk from the beach.) He also started by admitting that the subject of “guided help”…

…gets me excited. I don’t usually say this about any subject. We Brits don’t, you know. I’d usually say I’m “moderately pleased”. But guided help gets me excited.

A definition of guided help

“Guided help” is help that leads someone through a task using the actual application, while:

• Highlighting the controls (buttons, fields, etc) that the learner should use.
• Displaying instructions in a caption or panel.
• Preventing the user from doing things that they shouldn’t.
• Giving the user the option to skip through some of the steps by having them done automatically.

“Guided help” is not a simulation, such as a Flash movie or e-learning session. Nor is it a wizard.

The key thing is that the user is actually completing a task within the application itself.

A by-the-way: This is not new. In 1986, Matthew worked with Digital’s ALL-IN-1 office automation suite and created training sessions which included the above features. Now, twenty years later, we’re talking about “guided help”.

Microsoft Guided Help

In the early days of Windows Vista, there was a neat, attractive and impressive guided help available if you were online at the time you requested help.

Technical writers take note: CNET said that this was one of their top 5 good things about Vista! Matthew asks:

How often does that happen to us? People are buying the product just to read the help

Alas, guided help is no longer available in Vista. Microsoft’s stated reason is that it caused too many maintenance headaches — each time Windows was updated, they needed to check the guided help topics too. (Welcome to our world ) Matthew thinks this is odd, because the guided help hooks into the accessibility support built into the application and does not include screenshots. It should be easier to update than conventional documents. Perhaps the reason was rather a security concern?

You can still get hold of some Microsoft guided help procedures in the Microsoft Knowledge Base. Matthew ran the procedure which leads you through the task of checking your disk drive for errors. It was neat, attractive and impressive. It greys out the windows which you’re not using and highlights the buttons you should click, with a text box and an arrow pointing to the relevant spot on your desktop. You can stop the procedure at any time. If you do something unexpected, it warns you and asks if you want to stop the help session.

Another caveat: The authoring tools are available only to Microsoft and the OEMs.

Gteko

Gteko has been purchased by Microsoft. Before the acquisition, Gteko produced a free, downloadable tool called PCPal. It’s still available (ignore the fact that it’s beta – it has been for a while ) but the latest version does not offer as much control nor as much information as the earlier versions. Matthew has the earlier version, of course

If you delve into the depths of HP Assistant and DELL Support, they too are based on Gteko technology.

When you run PCPal, it takes over your machine, clicks the buttons, opens the windows, etc. It even moves the active window to the centre of your screen. It tells you what it’s doing, and asks for your input when necessary. For example, if you ask it to set up a screen saver, it will by itself get as far as the Windows screen saver selection dialogue and then ask you to choose the one you want.

ActiveGuide from Rocket Software

ActiveGuide one is targeted at the EPSS (Electronic Performance Support Systems) market. You can use this tool with any web-based application. It includes an in-built authoring tool, ActiveGuide Studio. Matthew says that you don’t need to be a developer to create the guided help.

ActiveGuide uses client-side JavaScript to add a layer between the application and the user, overlaying the additional UI components on the original screens. It doesn’t touch the code on the server. The help topics are associated with the UI components via the IDs attached to the form elements etc, not to the x-y coordinates. So to some extent, the help is independent of the presentation and of small UI changes.

Try this online demo. It opens “Form 1099R 2003″. Now you can:

1. Click “ActiveGuide Coach” at top right, to see the guided help in action.
2. Click through the introductory text panels — do make sure you read them
3. At the first selection, choose “IRA” — it’s the only one that works in the demo.
4. At the second selection, choose “E-Z Pass” (the third option) — that’s the most fun!

eTracker from Solan Technologies

eTracker is the same sort of technology as ActiveGuide and works on desktop client applications as well as web applications. Again, programming skills are not necessary to build the guided help. Matthew was told that you can create a complex script in four hours.

My conclusions

Thank you Matthew, for a very interesting session with lots of useful examples. At Atlassian, where I work, we’ve been discussing the possiblity of adding guided help to some of our applications. One of our products is FishEye, which we acquired when the Cenqua guys joined Atlassian last year. Earlier versions of FishEye had a pretty neat guided help tour built into them.

I’m really keen on adding guided help to our products. In particular, this sort of technology can to some extent protect the documentation from UI changes, because the help text is hooked to the screen elements themselves and does not rely on screenshots or instructions like “Click the xxx link at top right of the screen”. Also, the help is right there, where the user needs it.

Plus, it’s just plain fun to do