ffeathers — a technical writer’s blog

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. Today Rhonda Bracey took us through the long list of things we need to check and consider, when reviewing an application’s user interface.

Rhonda runs her own technical communication and consultancy business, CyberText Consulting. She has posted her summary of the AODC, day 1.

Reviewing a user interface (UI) is something that a technical writer is frequently asked to do. We are usually the first people to use a software application (or other product, I guess) after it has left the developers’ hands. Or even before. So Rhonda’s in-depth session was an excellent guide to the things we need to consider.

She covered a lot of detail about each of the following elements:

• Design elements — object placement, alignment, etc.
• Text elements — this is the most obvious arena for a technical writer, but Rhonda mentioned some items that are easy to overlook, e.g. the items in dropdown lists; the status bar; error messages; tooltips.
• Link elements — non-obvious ones here are the menu structures; links in images; links to online help; mailto links; and the consistency of link styles.
• Visual elements — graphics, colour and display. Take a step back and consider whether the graphics are necessary; size; what happens if the user turns the graphics off; what happens if the user changes the OS colour scheme, e.g. Windows is totally configurable; what happens if the user overrides or turns off the CSS.
• For web applications, test with different browsers; change the text size; turn off the JavaScript, cookies and frames; resize the window; test on different devices (even mobile platforms if relevant) and resolutions.
• For desktop applications, there’s a similar list of things to check.
• Click and press everything; try all options of the search and fill in every form.
• Check the speed and response times.

In particular, Rhonda had some good tips regarding translation and localisation, if applicable to your application. Here are a few I remember:

• On each screen, check whether the developer has left enough space for a translated UI — for example, German text is up to one third longer than English.
• Check for any logos or other images that contain text which will need translation.
• Watch out for culturally-specific terms or words, even within the same language e.g. American versus Australian usage.
• Consider the symbolism of specific colours in different countries.

To round off the session, Rhonda had some tips about giving your feedback to the development team, and some handy tools.

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.