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

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 15 May 2008, in AODC, online help, technical writing and tagged , , , , . Bookmark the permalink. 3 Comments.

  1. Hey! Nice article. You may be interested in our networking groups over on LinkedIn: Embedded Engineering, Safety-Critical Professionals, and DO-178b Love/Haters. Take this opportunity to network with other engineering professionals.

    Just go to my profile at and you can click on the groups to be included. While you are there, don’t forget to ask to link to my network of more than 9,000,000 like-minded professionals. I accept all invitations and look forward to meeting you.


  1. Pingback:   Weekly link roundup by Communications from DMN

  2. Pingback: Embedding help into the product - Taryn Sauer - Technical Communication and Instructional Design

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: