Blog Archives

Getting documentation feedback via customer forums – a story of UX and UA

I spend a few minutes each day trawling our online question-and-answer forum, answering questions when I can, and keeping an eye out for posts directly related to the documentation. This paid dividends yesterday when a customer asked where he can download the offline version of our documentation. After giving him the link, I delved a little deeper into his reasons for preferring the offline to the online version. It’s an enlightening discussion.

Kevin’s primary requirement was the link to the downloadable documentation. His question is therefore titled, Offline Confluence Documentation. I gave him the link. That was easy.

But the forum post also explains why Kevin wants the offline documentation. He mentions the fact that the online documentation was unavailable when he needed it. We did indeed have several problems with the server, now fixed.

It was this bit of Kevin’s post that caught my attention:

(Also the documentation has gotten much harder to use for experienced users because we need to wade through pages of fluff before we get to content found in the old user manuals right on the top level).

He had put that bit in parentheses, almost as if it’s not so relevant. That in itself is a worry for us as technical writers. We don’t want customers feeling that there’s no way of getting the documentation improved or getting their voices heard.

Also very interesting is the fact that Kevin describes himself as an experienced user. He knows the product (Confluence wiki) and he therefore also has an expectation of how the Confluence-based documentation will work. He wanted a quick fix for a problem (how to recover a deleted page) and was frustrated enough to resort to PDF to find it!

So I asked Kevin if he’d be kind enough to give more details about why the documentation has become harder to use.

His response was awesome. He described his troubled workflow in detail, giving us technical writers an excellent insight into how an experienced user is navigating through our documentation. If you’re interested in the details, take a look at this comment and the subsequent discussions.

It’s great when people take the time to respond like this. It shows a high level of commitment to the product and the various types of help that we offer, including the documentation and the forum. It also shows how willing people are to help each other. Thanks so much, Kevin!

AODC – usability of embedded help

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 8)

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

AODC – Adobe AIR Help

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.


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.

%d bloggers like this: