ffeathers — a technical writer’s blog

“Guided help” – that’s when you actually do the task you need to do, and some helpful bubbles or other UI prompts tell you what to do next. You’re not reading documentation, reading help or watching a video. You’re not working on a sandbox or a test site. You are actually getting the job done and learning at the same time.

I’ve recently tried SHO Guide, a tool for creating guided help scripts. It was a lot of fun and a very worthwhile experiment.

In a nutshell, this is what happens: Using SHO Guide, you write scripts and publish them. This produces a “.sho” file for each script. Your customers then use SHO Player (freely downloadable) to play the script. It hooks into the UI of your application and guides them through the steps they need to take.

First impressions

SHO Player is a quick download (1.3 MB). Installation is painless (apart from the usual chattiness from my Windows Vista OS). SHO Guide is a longer download (60 MB).

When you get your SHO Guide licence key, username and password, you also gain access to the “Resources” part of the SHO web site. This has plenty of tutorials, FAQ, a support forum and information about training. The Quick Start tutorial is very good. Fast, with just the right amount of information to get you started. It guides you through creating a SHO script for Notepad.

Creating scripts with SHO Guide

You can record a series of steps, by clicking the “Record” button in SHO Guide and then performing the steps in the application you’re documenting. Then you can go back later to edit, insert or delete steps as required. This is very useful.

The SHO Guide authoring environment has a familiar look and feel to people who have used various types of authoring tools:

SHO for guided help

(Click the image to expand it.)

On the left of the above screenshot are the two scripts I’ve created, called “Create a space” and “View all blog posts”. Underneath the scripts are two more segments, hidden at the moment, where you can access extra step types and a library of images and other resources. In the middle is the bubble that the users will see, with various options for you to create conditional paths, filters and actions. It doesn’t take long before you know what’s what and where to find it.

The easiest way to start a script is to record it. Here’s a screenshot showing a recording in action:

SHO for guided help

In the above screenshot, I’m recording an activity on the Confluence dashboard, running in Internet Explorer. The red square shows the UI element that is currently in focus. At the bottom of the screen is the SHO Guide recorder panel, showing the key presses already recorded.  The icon of a video camera at far right means that the recording mode is active and ready for input. The icon changes to a hand when the recording is paused or busy.

Hint: It can take a while to save a recorded action. Wait until the hand changes back to a video camera before continuing with the next click or exiting from SHO Guide, otherwise your clicks may not be recorded.

The end result

Here’s a screenshot showing the starter bubble of a script I created for Confluence, helping people to create a wiki space:

SHO for guided help

The problem: You’re new to Confluence, or to another Atlassian application. You have to get something done, and you’ve no idea where to start. You’re panicking. You’re in a hurry. The UI is not helping, because it assumes at least a bit of knowledge. Atlassian, WTF??

The solution: Atlassian WTF!! The Atlassian Webapp Tutorial Fantastique.

Curious about the fairy in the bubble? She’s the Atlassian Webapp Tutorial Fairy, of course. She’s also a photograph of my earring. You can add images, videos and documents to your SHO scripts.

Here are a couple more screenshots of the same script in action:

SHO for guided help

So the user would click the “Create a space” link, as prompted by the green bubble. Confluence then opens the “Create Space” screen and SHO supplies the next bubble, prompting them to enter the space name.

SHO for guided help

In the screenshot below, see how you can present a choice of paths to the user. In this case, the “Do It For Me” option launches a set of automated steps — another cool feature of SHO.

SHO for guided help

The user also has the SHO Player toolbar, allowing them to pause or stop the script:

SHO for guided help

Want to see and read more?

Experimenting with and evaluating SHO was my Atlassian FedEx Day project. There are more screenshots in my FedEx 12 delivery note, as well as some notes about the requirements and limitations of the tool. What on earth is FedEx Day, you ask? It’s a period of 24 hours when Atlassians get to do something totally different from our normal day-to-day job, then present our findings to the rest of the company. It’s pretty cool. I wrote about it last week.

Wrapping it up

This was my first foray into guided help and into SHO. A big thank you to Matthew Ellison for mentioning SHO in his presentation on context-sensitive help at AODC 2009. (I wrote about it too.)

BTW, this was just an experiment. The scripts aren’t by any means production ready.

I haven’t had time to investigate SHO in detail. There are many possibilities, such as including sound, video and documents into your scripts, adding specific action types, trapping errors issued by the app, and so on. SHO Guide is easy to download and you can evaluate it for free for two weeks. The Transcensus guys, makers of SHO, have been very friendly and free with offers of help and discussion. Definitely worth a try. Fun too. That’s what it’s all about, huh.

This week I’m attending the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. Today is the second day of the conference.

Here are some notes I took from the session on user-centred design of context-sensitive help, by Matthew Ellison. I hope these notes are useful to people who couldn’t be at the conference this year. The AODC organisers will also publish the session slides and supplementary material once the conference is over.

User-Centred Design of Context-Sensitive Help

With a laugh, Matthew introduced himself:

“I am the equivalent of Tony Self but with a funny accent and a better shirt.”

In this presentation, Matthew concentrated on the information design side of things, rather than the technical implementation of context-sensitive help (CSH). He gave us a definition of CSH: “Direct access to help that is focused on the user’s current needs.” In practice, he said, we tend to provide help based on where the user is in the UI.

What do we mean by “context”? The more we can tie it down, the better help we can provide. For example, we might be able to detect and respond to: The window/dialogue/tab the user is on; the control they’re trying to use; the zoom level or other settings; previous history, such as other screens visited; role; printer connectivity and so on.

Looking to provide user-centred help, let’s look at how users behave with respect to help:

• Most people don’t consult the help ahead of time.
• They’re usually busy with the task when they need help.
• They’ll only use help if they think it will give them useful information. So Matthew says they’re unlikely to click a little question mark, because it is not a convincing indicator of useful information.
• They want to be interrupted for as short a time as possible.

We also need to consider the questions a user may ask when confronted with a task or screen. For example: What is this screen for? What do I need to enter in this field? Matthew thinks it’s unlikely they want task information in a context-sensitive topic, because they’re already busy with the task.

Matthew has noticed that some software vendors are moving towards procedural rather than reference topics. (For example, see the CSH for MadCap Flare from versions 3 to 4.) Apparently this is in response to feedback from users. But Matthew thinks this may be a misdirection.

As a consequence, one mistake the Flare help makes is to pack all the reference information into the step in the task topic. So for example, there may be a single step that tells you to complete the options on a screen. This step will now be very long because it contains all the reference information about each option.

By the way, Matthew remarked that he is a great fan of MadCap help.

In the Captivate help, the help links are now labelled as “Learn more” with an information icon. Unfortunately the help topics are very long, especially for online help use.

So Matthew thinks the CSH topics should answer the questions: “What is this? What should I enter? Which should I select?” And the topics should be written specifically for CSH rather than linking only to documentation written for other purposes.

Now Matthew discussed IBM’s Task Support Clusters, designed by Michael Hughes. The idea is that most people who use their help are coming in via CSH. They press help within the application rather than coming in via search.

So IBM identified the locations in the application where help is needed, and then built a self-contained group of topics that support that particular task.

Start with a keystone concept topic (provides critical conceptual information), then provide related tasks and reference. The topics in a cluster are all interrelated by links pointing to each other, but there are no links that point outside the cluster. So the users cannot get lost by following links all over the help system.

The idea is that 80% of the time, the users will read the keystone concept topic and that will be enough. Don’t try to answer all questions in this topic, just the most likely questions users will have.

Now Matthew discussed contextual help. This is additional information that’s actually part of the application and supplements the UI. It’s more likely that people will read this, because they don’t have to open up the help.

This is inline help, available via popups or expanding/dropdown text, or just simply on the screen. This help must be well written, because there’s very little space. Recommended length is one to three short sentences for the entire page. But just one phrase or sentence for a single field.

For the help links, use the actual question the user may ask e.g. the link might say “What is a member name?” When you click it, you get a popup answering the question. Or “See some examples” might pop up some example values for a particular field.

MadCap Flare has this kind of popup help. They’re also working on the functionality that will allow us to put it into our own help systems when using Flare — currently only for DotNet applications.

Quick help or popups should link to full help system for deeper information. MadCap Flare is doing this in their new popup help.

SnagIt’s balloon help is great — it knows what you’ve just done and suggests what you might want to do next. After a while the balloons disappear, because it assumes you know how to do it now.

Also guided help may be a good way of providing procedural help. See Matthew’s presentation from last year’s AODC conference. The application guides you through your task and actually stops you from doing the wrong thing. SHO Guide is a very interesting product that allows you to do this.

Thank you for another great session, Matthew.

This week I’m attending the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. Today is the first day of the conference.

Here are some notes I took from the session on enabling feedback and collaboration in online help systems, by Matthew Ellison. I hope these notes are useful to people who couldn’t be at the conference this year. The AODC organisers will also publish the session slides and supplementary material once the conference is over.

Enabling Feedback and Collaboration in Software Help

Matthew Ellison introduced some ways of making traditional help systems more wiki-like, by allowing collaboration and feedback within the online help system.

Matthew asked us to consider what most people do when they have a problem. Instead of going immediately to the help, they ask a colleague if they’ve had the same problem. Next they might try a Google search, visit the forums, look up the FAQ, knowledge base, etc. The last thing they try is probably the online help.

• Google search, forums, etc, help with problems that are not typical use cases i.e. something that the help author has not anticipated.
• Also the social aspect plays a part: we’re social beings and we like to talk to each other and help each other sort out problems.

Matthew listed some help technologies that show a trend from where the help is stored on the desktop (collaboration difficult) to the server (enables collaborative feedback and commenting):

• Windows Help (.hlp) — Ahead of its time because you were able to annotate help files, but this is only for your own purpose not collaborative
• HTML Help (.chm)
• JavaHelp
• Oracle Help
• Browser-based help
• Oracle Help for the Web
• Server-based help
• Eclipse Help
• Adobe Air help — Used to provide the help for RoboHelp, for example.

Web-based help allows you to link from other locations directly to the official help. For example, you could link from user forums to the help. Or the support staff can link to the help. Matthew said that he has not seen links in the other direction e.g. from the official help to the forums.

(A quick note from me: We do link from the Atlassian documentation to the forums, blogs etc.)

Matthew is suggesting that we may be able to have a help system that is much more integrated e.g. instead of having the forums and the help in separate places, we could merge them. There is still a place for the official help, that provides trustworthy guidance and instructions. And if there are problems, at least the reader can take it up with the company concerned.

(Matthew said at this point that, as far as he knows, context-sensitive help is not available in a wiki-based solution. This is another thing we have implemented at Atlassian. See this blog post and this one.)

Now Matthew asked why we should enable feedback and collaboration in help:

• Users like to contribute and share information.
• We can use their comments to improve the help.
• Shared comments improve the users’ experience of help.

He gave a number of examples of simple feedback mechanisms in existing help systems, where the online system provides a way users can rate their experience of help. Typically, the help system asks if the information was useful, and offers you a text box to provide feedback. Examples are QuickBooks Help, eBay Help, Yahoo Help.

Some more sophisticated examples:

• Adobe Help Viewer, used for FrameMaker, Captivate, RoboHelp. Built on Adobe Air technology. Allows you to add comments, via an optional pane at the bottom of the viewer. You have to sign in with an Adobe ID in order to provide the feedback. You can also choose to keep the comment private i.e. not visible to other users. It also sends a confirmation email when you add a comment, and awards you some Adobe Community Help points. This gives you a warm feeling, said Matthew with his trademark smile
• Help for Adobe Captivate — You can see the comments from other users in the comments window. So users can even start a dialogue with each other via the comments.
• Help for Flare, by MadCap Software, allows the same level of collaboration. The help is delivered in DotNet help format, embedded in the product. At the top of every topic is a bar allowing you to rate the topic. You can rate the topic, see the current rating and provide feedback. You can also see all recent comments for all topics. Matthew comments that the options are not very visible. The help author at MadCap says that it’s not much used, probably because it’s not very visible.

As a help author, you can do this kind of thing in your own help system:

• You can simply add a mailto link. Or you can add an HTML form, allowing people to send comments. Use server-side scripting and a database connection.
• DocCommentXchange (DCX) from Sybase is a proprietary comment-enabled web-based documentation. Users can submit comments. Based on GWT (Google Web Toolkit) and a SQL Anywhere database server. (They presented a case study about it at WritersUA 2009. This required a fair amount of technical knowledge, so is not the solution for most people.)
• You can use Adobe Air Help. You need to create your help in RoboHelp and generate the output as Adobe Air Help. You can allow users to comment on topics and view previous comments. However, they can only share comments with other people on the same LAN, not across the internet.
• MadCap Flare provide a feedback server, or you can use their hosted service. Users can provide topic rating and feedback to the author. You can share feedback via the web with all other users of the application. Can do it with any help format (DotNet Help, HTML Help, WebHelp, WebHelp AIR, WebHelp Plus). You configure the options when you generate your help system. It will also send an email to the author when a comment arrives, asking the author to approve the comment and thus make it visible to all users.

But Matthew noted that, to date, the feedback volume is low in the systems he has investigated. People prefer to give their feedback via forums, rather than in the help system.

Also, remember that you need to set up mechanisms to collect and analyse the data, act upon it, and respond to contributors.

Thank you Matthew for a detailed and interesting talk.

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