ffeathers — a technical writer’s blog

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

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. In one of today’s sessions, Colin Dawson talked to us about an application he has developed and the online help he has included in the application.

Colin is a very experience technical writer, trainer and consultant. He has developed an online timesheet system, with online help in three forms:

• Menu-based online help — this is the usual sort of thing one might produce via a help authoring tool, typically including a table of contents plus the help topics, sometimes an index and a search.
• Embedded help — concise text in a panel on the application screen (UI) itself. Colin calls this “mini-help”. Users can collapse the panel, and it will stay hidden until they expand it again. (More below.)
• User-contributed help — users themselves can add help topics to the application screens. (More below.)

Embedded help

After a couple of years of design and usability testing, Colin has formulated definite and well-articulated principles for an embedded help system. Here are the points which I picked up, though I’m sure there were more which I missed

• The embedded help content should not be a hard-coded part of the application. It should be sourced from a separate file, and should be owned by the technical writer rather than the development team.
• The text has to be concise, because there’s not much real estate on the UI.
• The text must link to the more detailed menu-based online help system.
• It goes without saying, but let’s say it anyway: the text must be context-sensitive i.e. it must relate to the screen on which it appears.
• The help topics for the embedded help must not be visible in the menu-based help system. Hide them from the table of contents, index, search. They would just be misleading. (This may seem a no-brainer to people who haven’t developed online help systems. But it needs to be said, because the writer will need to instruct the help authoring tool to exclude these topics specifically.)
• Tooltips and popups are evil — intrusive and the users have no control over them. They often even hide the screen content.

User-contributed help

Colin’s application allows the users to add their own help items to each application screen. He calls this “Our Help”. This functionality is roles-based, i.e. different users have different roles and therefore different create/modify/view permissions on the help items. Each user-contributed help item can be:

• text
• an image or other file
• a link to an external location

The users/customers can contribute their own information, supplementing the technical writer’s knowledge.

This idea ties in nicely with other AODC sessions this week — for example, see my earlier blog posts on “AODC - a new grammar for online communication” and “AODC - trends, tools, technologies in online documentation”.

Colin’s system also gathers information about the usage of the help system and the user-contributed help items added. He emphasized that such user-contributed help must be monitorable and traceable.

Usability testing

Colin has spent a lot of time researching the usage of the application and the help. In one set of tests, he compared the user interaction in (a) the application with both embedded and menu-based help, and (b) the application with only menu-based help i.e. no embedded help. Survey results showed that:

• If the embedded help was present, many more people knew that the application had a help system. If only menu-driven help was present, people did not find it — even though the “Help” link was on every application page.
• More people completed the set tasks if embedded help was included.
• More people were confident about using the system to complete the set tasks if embedded help was included.

After the session

I spoke to Colin after his session, because this is a topic very dear to my heart

A month or so ago, quite independently of today’s demo by Colin, I suggested to Atlassian (where I work) that we should add a function to our software products which allows our users/customers to contribute their own embedded help topics. During his talk today, Colin mentioned that he does not know of anywhere else where such a thing is done. Neither do I. It would be interesting to know if anyone else has seen this sort of functionality.

Colin has a patent pending on his “user-mediated embedded help”. He is happy for me to blog about it. He will also be launching his product, with its help system, at CeBIT Australia in a few days’ time. Good luck, Colin!

Update on 26 May 2008: Colin’s timesheet system has a new website: etimebiz

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. At today’s first session, Tony Self introduced us to AIR (Adobe Integrated Runtime) and two prototype AIR Help applications.

Tony is a founding partner of HyperWrite. His sessions are always amusing and information-packed. This one was no exception.

AIR

First, Tony introduced AIR itself. The acronym stands for “Adobe Integrated Runtime” and is produced by, you guessed it, Adobe.

In brief, here’s what happens:

• As an author/developer, you will create an AIR application.
• You will send the application to your users — it’s just a single file (extension .air).
• Your users will install the AIR platform first, then install your application.

Since Adobe has such a wide following and presence, it’s thought that the AIR platform will soon be as prevalent as Flash, i.e. approximately 97% of computers will have AIR installed.

Here are some of the things AIR does for you:

• You can create a rich desktop application, including graphics, HTML, AJAX, Flex and Flash.
• An AIR application can be installed and run on any operating system. Well, in principle anyway.
• Your application can include content from local and remote sources. Tony mentioned a good use case here: Your application could fetch the online documentation from the server if your user is online, otherwise it could default to the local copy of the documentation.

Two AIR Help applications

Next, Tony gave us an demonstration of two uses of AIR to produce online help systems:

• Scott Prentice’s prototype AIR Help application
• Adobe’s pre-release AIR support for RoboHelp 7

Scott Prentice’s prototype AIR Help application

Scott Prentice has created a prototype AIR Help application, using a DITA document as a test case (the DITA language reference). Scott’s application allows you to view the DITA document in a rich desktop viewer. The navigation panels include two different tables of content, an index and a search.

Adobe’s pre-release AIR support for RoboHelp 7

Adobe is building AIR support into RoboHelp 7. Currently, this is available as the pre-release RoboHelp Packager for Adobe AIR. The packager is free, and likely to remain so. It is also open source. It will probably become another output option in the RoboHelp UI.

To use the packager now — assuming you have RoboHelp installed:

• Download and install the AIR platform.
• Download and install the RoboHelp Packager for Adobe AIR.
• Generate your WebHelp output from RoboHelp as usual.
• Then run the packager, giving the location of your WebHelp files as input.
• You will need a digital certificate. When you distribute your application, your users will use the certificate to verify the source of the executable file. For testing purposes, the packager leads you through the process of generating a certificate on your own machine. When you eventually distribute your AIR application, you’ll need a certificate from a recognised authority.
• You can set various look-and-feel options, such as number of tabs, skins, branding. The number of available options will probably increase when the product is more mature.
• You can configure your application to allow your users to add comments. Wow, Web 2.0 (More below.)
• You can also configure it to update the local AIR Help file periodically from the server.
• Click the “Generate” button — the packager will produce a file with the .air extension. This is the file you will distribute to your users.
• Your help application supports context-sensitive help.
• You can also bundle the help application with the product (application) it is documenting.

Now put on your other hat and become a user of your help system. Double-click the generated xxx.air file to install it.

• You should see the content of your help file in the AIR Help viewer. It will look very similar to the RoboHelp WebHelp output. After all, it’s the same HTML.
• It includes a search facility, which also shows a summary of the contents of the pages in the search results.
• There’s also an index.
• It allows users to add “Favourites” — this is difficult to do in straight HTML-based help.
• The “How do I” facility is similar to RoboHelp’s Browse Sequences.
• There’s a sophisticated zoom utility to increase text size.

A bit more about the comments in the Adobe AIR Help

When you use the Adobe packager to create an AIR Help file, you can configure your application to allow your users to add comments.

A user can then add comments to the help topics. By default, the comments are stored on the user’s local machine. Each user can see a list of and review their own comments. They can also choose to synchronise their comments with the server. Then their comments are visible to other users, and they can see other users’ comments.

Tony mentioned that this is a bit of a trend in online help software, for example MadCap Flare can now run with the MadCap Feedback Server, which collects comments as well as information about how the users are using the system. This is useful, for example, to diagnose troublespots in the help system and the application it is documenting.

My conclusions

Tony’s session was very interesting to me, because I’ve produced various help systems such as WinHelp, HTML Help and straight HTML files, using RoboHelp, Help & Manual, HDK and others lost in the mists of time From the little bit I’ve seen today, AIR Help is one to keep an eye on. It’s not a leap into the future, but it has some useful advantages over CHM files and vanilla HTML.

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. Yesterday afternoon, Joe Welinske presented a session entitled “Trends, tools, technologies in online documentation”.

Joe is the president of Seattle-based WritersUA. Yesterday’s session gave us some good insights and discussion points based on the results of the WritersUA Skills and Technologies Survey. I’d recommend a quick look at the results on the linked web page.

General points

Here are some points from Joe’s talk which I found particularly interesting.

• Looking at the user assistance skill set, a list of things we technical writers do — it’s a long list, though it does fit on one slide Joe asked us whether we had all done most of the things listed. I have, and I think most people had too, in the course of their careers in technical documentation.
• Tools — Adobe controls 60% of the tools we use. Madcap Flare’s market share keeps growing.
• Skills we need for online documentation — include technical geeky things like XML, XSL, XHTML, DITA as well as the core skills like HTML, CSS, graphics etc.
• How we get training in these skills — 64% from on-the-job training. 22% by learning on your own. This confirms my own experience.
• Publication media — More than half of the respondents said that they preferred printed manuals! Also, 83% indicated Adobe Acrobat, which is close to printed manuals. Embedded user assistance is on the rise.
• IBM is working towards replacing Eclipse Help with DITA Help.

Analysis of help in Microsoft Vista

Joe walked us through a very interesting analysis of user assistance in Vista, as a method of divining Microsoft’s direction for the future of help in Windows and their idea of best practice.

HTML Help was first released in 1996, and updated in 1998. Since then it has kind of stagnated. Yet it’s still Microsoft’s recommendation for online help development.

The online help in Vista:

• Presents in a single window — no separate panel for navigation bar / table of contents.
• Has no index.
• Uses search as the main navigational component. This may work if the search is good, but is tiresome if you get too many hits.
• Includes a lot of rich information. Microsoft is not going for minimalism in their documentation.

Also, Vista embeds a lot of traditional help content right on the UI, as text on the screens. The goal is to make help unnecessary wherever feasible. This means that technical writers must be involved in the UI design. We must be able to put ourselves forward at design time and say, “This is something I’m really good at.”

Other developments technical writers must be aware of

Technical writers and communicators need to keep in touch with new developments and philosophies, such as:

• Mashups — integrated, unrelated applications, which will need online documentation of some form or other.
• Web-based API documentation — growing demand. Google is a big employer of technical writers in this area.
• Custom devices — OLPC (One Laptop per Child), PDAs, phones, other mobile platforms. How can we deliver documentation that works on these platforms?
• Structured authoring — affects a growing number of technical writers. Joe sees this as the most important concept for us to learn about. It affects our roles and production process. The author works in a form-based environment, putting the content into pre-determined pigeonholes. Presentation is separate and automated.
• Web 2.0 — collaboration and the ability of our readers to interact with the content. We need to wrap our heads around what this means for documentation.

My conclusions

Thank you Joe for a great overview. I’m looking forward to hearing more from Joe in the next few days of the conference.

Online help — it’s a technical writer’s dream. We all want to design and write online help systems, and we all know that context-sensitive help is the way to go. Can you do it on a wiki?

Yes I wrote an article on the Atlassian News site this week, illustrating how we’ve used our Confluence wiki to provide context-sensitive help in the latest FishEye and Crucible software releases. Have a read. It’s got some pretty pictures as well as the technical stuff

Clarifying my terminology: By ‘context-sensitive help’, I mean that when you click a help link on an application screen, you get the instructions directly related to that particular screen. Also at a deeper level, when you click a help icon next to a field you get help on that specific field. We’ve provided both these levels of help, as described in the above article. Another type of contextual help is when you hover your mouse over a field and a short description pops up in a kind of bubble. That’s usually called a ‘tool tip’, and is not what I mean here.

I’ve written a number of online help systems for various companies, using a variety of tools. My favourites were Help and Manual and RoboHelp. I’ve also dabbled with HDK (the precursor to XDK) and with Microsoft’s ‘raw’ HTML Help editor. And now I’m using Confluence wiki.

What’s the difference between a wiki and a help authoring tool? Well, there’s a big difference, of course. A wiki is essentially a collaboration platform — your online documents become a place where everyone goes to find information, share their own tips with others, and pick up the latest updates. A help authoring tool is tailored towards building a documentation set which is essentially static (even if you update it every day, it’s still not a discussion platform) but which has all the bells and whistles of an integrated online help system.

Most help authoring tools provide the following functions. You’ll probably have trouble finding a wiki which supplies these functions to the same degree:

• Fully customisable table of contents, where you can put topics in the order you want, omit topics, or make a single topic appear more than once.
• Integrated keyword index.
• Integrated glossary.
• Navigational tools to make topic browsing easier, such as the ‘browse sequences’ provided by RoboHelp.
• Topic linkage tools, such as the ‘next topic’, ‘previous topic’ and ‘related topics’ tools which are built into some help authoring tools.
• Generation of HTML Help (.chm) and WinHelp output files.
• Workflow support (draft, review, publish).
• Integration with a source control tool such as VSS, or RoboHelp’s inbuilt check-in check-out manager.
• Automatic generation of topic IDs, which you can hand over to a developer for plugging into the code to generate context-sensitive help links.
• Sophisticated topic templates.

That’s a long list. So what does a wiki provide, in terms of usefulness for online help?

• A wiki page is just a URL — so you can link to the page directly from your application screen. (Read my Atlassian News blog to see how we’re doing it with Confluence.)
• Wiki pages are continuously being updated and enhanced by technical writers, support staff and even customers who have useful tips to share. So when someone clicks the help link, they get the most up-to-the minute information possible.
• Wikis allow you to embed multimedia goodies such as images and Flash movies.
• You should be able to generate PDF, HTML and XML versions of your wiki pages.
• A good wiki has a good search engine.
• Some wikis provide version control — all changes are tracked, and you can see who made each change or even revert to a previous version of a page.
• A wiki often provides tools for runtime integration with other software — many wikis allow you to install plugins or addons which display information directly from another platform. For example, a wiki page can show a list of bug fixes drawn dynamically from an issue tracking system like JIRA.
• Some wikis allow blogging as part of the wiki platform. So your documentation page can embed a list of the latest blog posts related to the topic of the page. The blog posts will always be the most recent as at the time the user views the wiki page.
• Your wiki is sure to have a number of other interesting features which you can use to work around some of the shortfalls listed above. If you’re interested, take a look at my previous posts on using wikis for technical documentation.

In short, wikis are different. They’re not necessarily better or worse — it depends what you need for your documentation system. Wikis are fairly new, so they’re developing all the time. I’m having fun riding the wave