AODC – in conclusion

Last week I attended the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. I’ve posted a number of detailed reports on the sessions I attended. This post is a summary and a “thank you” to the organisers.

A big thank you to Penny Bradley, Tony Self and HyperWrite — you did an awesome job, with not a hitch to be seen! I learned a lot, met a lot of people and laughed a lot. It’s valuable to see what other technical writers are doing, because we all tend to work in a particular technology or field and can feel isolated from the bigger picture.

Best of all, I now know how to pronounce “DITA”. It’s “ditter”, or even “didder” and not “deeter”. This handy distinction avoids confusion of the XML standard with Dita Von Teese.

Summary of AODC posts

Here’s a list of my blog posts on the sessions I attended:

• AODC – DITA workshop
• AODC – trends, tools, technologies in online documentation
• AODC – a new grammar for online communication
• AODC – web technology and standards
• AODC – a DITA case study
• AODC – usability of embedded help
• AODC – reviewing a user interface
• AODC – authoring memory
• AODC – separating content, structure, format and behaviour
• AODC – guided help
• AODC – error messages

You can also get to the above posts via the AODC tag.

And here are some other interesting posts on and around the conference:

• A summary of AODC day 3 by Rhonda Bracey, one of the conference delegates — see her other posts on the AODC too, for excellent summaries and commentary.
• Tech writer’s spot — Elena Shebunyaeva comments on the “nu grammar”.
• Travelling Worm in Surfers Paradise — a review of the conference location from a hanger-on.

Next year?

I work at Atlassian. One of our products is a wiki called Confluence. Following the principle of eat your own dogfood, we do all our technical product documentation (well, almost all) on the Confluence wiki. For example:

• The Crowd documentation on our Confluence site.
• The Confluence documentation, also on the Confluence site.

At the AODC conference, a number of people were interested. What’s it like to do technical documentation on a wiki? What works well, what doesn’t? Why do we use Confluence for our documentation? Can customers contribute to the documentation? What process do we use to review changes made by people other than the technical writers? These were just some of the questions people asked me. Tony suggested that this would be a good topic for a session at next year’s conference. There’s certainly enough to talk about, and of course I find this topic exciting and absorbing

Pictures

Here are some snaps to make you wish you’d been there. First, the venue — Surfers Paradise on the Gold Coast, Queensland, Australia:

My name tag, fairly unadorned because I’m uninteresting i.e. this was my first AODC session and I come from a boring state in Oz:

A more interesting name tag:

If you are unfortunate enough to hail from New Zealand, you get a kiwi or a sheep (depending on the whim of the name-tag creator) instead of the Ozzie state. If you’ve attended a large number of sessions, you get the superman logo and are dubbed a super-veteran. I’m not sure what Marian did to get the no entry sign superimposed over her superman logo! The sun means something too, over and above the fact that it shines out from you and there are yet other pictures with meanings I’ve forgotten. Can anyone list the name-tag adornments?

My Prickly Paperbark tree

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:

AODC – error messages

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.

AODC – guided help

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

AODC – separating content, structure, format and behaviour

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. With his inimitable flair and style, Dave Gash presented a session this morning entitled “The Search for the UA Grail: True Separation of Content, Structure, Format and Behaviour”.

Dave is the owner of HyperTrain dot Com, specialising in training and consulting for hypertext developers. Today he told us what’s wrong with the way we traditionally do things, what’s wrong with the conventional wisdom on how we might improve our way of working, and what’s a better way.

What’s wrong with the traditional way we do things

The basic problem is that we write our content, e.g. a web page, and tweak elements of it on the fly. For example, we might make some text bold, or colour other text, or whatever. The result is spaghetti code — difficult to maintain and share.

What’s wrong with the conventional wisdom on improving the above situation

People usually say we should “separate format from content”. But what is “format”? That term is too vague. And the phrase implies that everything that’s not “content” is “format”. Wrong.

The better way

We should separate our document into four components instead of two:

• Content (which you might realise via XML)
• Structure (XSLT)
• Format (CSS)
• Behaviour (JavaScript)

What we’re aiming for:

• Maintainability — you can change one of the above four components without breaking the others.
• Re-usability — you can re-use the same bit of JavaScript, for example, in other documents.
• Separation of skill sets — different people can work on the component they know best and enjoy most.
• Simplified updating of content — content is likely to be the component you update most often.

How to do it

Dave demonstrated the procedure we would follow in order to separate a document into the above four components. There are five basic steps. Dave walked us through the details of each step, using code examples of CSS, JavaScript, XML and XSLT. In summary, the steps are:

1. Identify all JavaScript and move it to an external JS file.
2. Identify JavaScript that could be better done in CSS. Examples are “onmouseover” and “onmouseout” event handlers that change the style of the text item, and image swaps. Use the CSS “hover” pseudo-class instead.
   • Dave’s tip: You don’t have to specifically code the “I’m through hovering” handler because it’s implicit in the pseudo-class.
3. Move all CSS styles to an external file. Convert local formatting to classes too.

   Dave’s tip: If the boss says “Change the list spacing in all lists on all pages”, it’s in one spot — change it and take the rest of the day off.

4. Add semantic markup to the content, using XML.
5. Now it’s time for some XSLT. Identify the output HTML you want, then write the XSL transforms to produce it.
   • Write small, individual templates to create the HTML for each specific XML tag. Then use the “magic” <xsl:apply-templates/> element to pull it all together. This nests the processing of the templates, so that the transforms will just keep happening for each XML element, hierarchically down and back up the tree, until they’re all done.

The XSLT generates the HTML and links in the CSS and JavaScript.

Dave has made the code available on the “Downloads” tab of the HyperTrain dot Com web site.

A recommended editing tool: EditPlus.

Thank you for a great session, Dave. And a special thanks for changing “behavior” to “behaviour” throughout your presentation, just so that we Ozzies felt comfortable