The hard road to user-friendly help

When you're designing a user assistance architecture, you often run into conflicts between what is best for your users and what presents the fewest technical challenges.

For example, a couple of years ago I had to design a Related Topics feature from scratch to overcome some limitations in our authoring tool. I developed several models. Some used XML to dynamically generate lists of related topics, while others relied on metadata tags and elaborate scripts.

Security issues made the design process tedious; the feature had to work on local hard drives under the Windows XP SP2 local zone lockdown.

In the end, I was able to come up with a model that was both reliable and user-friendly. There was only one problem: because of complexity, the feature was a nightmare to implement.

Every time I see that feature in the help, I have mixed feelings. I'm usually inspired by how reliable it is, and how it provides a user-friendly way to navigate through the help topics. But then I cringe at how difficult it was to develop and implement in a project.

Was it worth it?

Good question. Yes, I think so.

Why?

Unless higher priorities exist that would make the help even more user-friendly, I think such enhancements are worthwhile.

The bottom line is that users don't have to experience a single moment of the tedious work that went into that feature. They just experience the fluid and intuitive lists of related topics that guide them to the answers they seek. They only see the good side of the technology.

As a help author, my job is to create the most user-friendly help I can. Sometimes there is no tool to make a job easy, but I do it anyway, because those challenging features help to separate our products from the competition. Every technically difficult feature they choose NOT to implement makes our product better by comparison.

(Also, I have a confession to make. I'm way more content when I have a technical challenge or two to keep me from getting bored.)

Are you struggling with a technical enhancement? Don't give up. Your users will appreciate the work, and you'll learn a lot from the process.

Feel free to share your struggles by leaving a comment. Perhaps someone will suggest just the solution you're looking for!

Similar posts:

• Simple ways to improve the usability of help
• What users want from help content

Betrayal - Software is boring sometimes

Every now and then I get tired of software and want to write about something new.

Wow, I feel a bit guilty writing that, like I've betrayed a close friend or something. But it's true. I'm feeling a bit stifled lately, like I need to spread my wings.

I'd love to write about something tangible for a change. How to hit a line drive off the sweet spot of a Louisville Slugger, or exit a corner with enough speed to redline third gear.

"Documentation" is a big word. Bigger than just "F1".

2,600 years ago Taoist sages were writing documentation on philosophical matters. Cave paintings depict bison hunts that took place long before that. (I wonder when the first peanut butter and jelly sandwich was made. Did the chef chisel the instructions on a stone tablet that has yet to be found?)

The user manual is far older than the personal computer. There are so many things to explain that do not have system requirements, installation instructions, or bug reports.

Maybe I just need to "unplug" for a while and feel the sun on my face. Fishing would help; the whirring of line through an open-faced reel is poetry.

But all of this is temporary; the result of working long hours under the glow of fluorescent lights... staring at software.

I'll come full circle, eventually.

In time I'll stumble across a vintage computer with fake wood trim that will call out to me. My pulse will increase a bit as I turn it on and watch the monochrome glow of the operating system coming to life.

Then the command line will call out to me like a new world waiting to be explored. Once again, I'll be knee deep in software.

Related topics:

• The art of technical writing
• Technical writing and consumer emotion

22 things to check before publishing a technical manual

Many of us spend a significant amount of time looking over manuals prior to publication. Even the most carefully written guide will have a few typos, pages that break in awkward locations, or a table of contents with incorrect page numbers.

Catching these issues and fixing them requires a trained eye. You need to know what to look for. In such times, it helps to have a checklist of issues to watch for during your proofing pass.

Here is a list of items to watch for when taking a pre-publication look at your work or that of your peers. You may want to keep a printout of your document template handy so that you can double check the document against the formatting in the template.

• Flip through review copies and make sure all comments from reviewers were incorporated
• Spell check
• Regenerate the Table of Contents, or at least spot check the headings and page numbers
• Verify that the headers and footers alternate correctly
• Verify that the headers match the chapter titles
• Verify that the pages are sequentially numbered
• Check the copyright date to insure that it includes the current year
• Look for images that extend beyond the margins and adjust them, if necessary
• Look for images lacking clarity and reshoot or resize them
• Check a printout for images that don't show up due to printer errors
• Scan a printout for any strange characters or font-substitution issues
• Scan for numbered lists and ensure that they are sequentially numbered
• Search for any notes to the writer that haven't been removed or hidden
• Look for pages that break in awkward places
• Verify that trademark symbols are used appropriately for your products and others
• Verify that the appropriate cover pages or end pages have been attached, if necessary
• Check for images that do not match information described in the text
• Regenerate any cross-references to ensure they are up to date
• Regenerate the Index, or at least make sure page numbers are up to date
• Check the formatting of headers and footers on special pages, such as the cover, copyright, and first pages of chapters and verify that they match your template / conventions
• Check for recent convention decisions that may have been made after the document was written
• Look for long tables that break across pages and verify that the column headings are repeated on each page

This list obviously isn't comprehensive; every document is different and offers unique proofing issues. If I missed anything important, feel free to mention it in a comment.

Similar topics:

• 11 tips for writing incredibly useful procedures
• Six ways to improve your help authoring workflow

Building the next generation of help

"To launch the holographic virtual assistant module, press F1 now and move three steps to the left of your terminal."

Ok, I'm willing to admit that the above scenario is more likely to appear in a lousy science fiction novel than in the homes of actual computer users, at least in the near future.

But, help is changing.

The question is, how should help evolve so that best meets the needs of users?

The Dr. Frankenstein approach to building help

Software, like humanity, progresses in bursts. It leaps forward, stumbles back a step or two to catch its balance, and swerves sideways to adjust for environmental hazards. Often a software release is less reliable than a previous version. Sometimes a release includes features that no one really uses. But, over time, the software gradually improves as developers gather more and more information and feedback from users.

Help authors can see this need for direction and feedback by taking a look at popular user-assistance delivery models and the latest help authoring tools.

The RoboHelp Packager for Adobe AIR, for example, is betting that "help as a separate application" will continue to meet the needs of users, if the platform features are robust and user friendly. AIR help offers user-selected favorites, comments, tabbed browsing, automatic updates, and more. If the Adobe team can get enough users to install the AIR plugin, or enable AIR help to run on a server (thus negating the need for users to have the plugin), I'd be willing to bet on the future of AIR help. My initial experience with the format left me quite impressed.

However, others preach the benefits of embedded help. By placing help content within the interface, technical writers can offer assistance that is less intrusive and easily associated with the appropriate context. Hmmm... this sounds like a great idea also.

Given that embedded help and "help as a separate application" are practically opposites, how do we plan for the future and reconcile such differing approaches?

Perhaps a blended approach would work best, with embedded help serving as a front line of defense and a more-robust help system offering more detail when necessary.

But the only way to really know is to gather more feedback about how users access help. This requires time for usage data to accumulate, and...

Ubertools (and the implications thereof)

Many tools are emerging to provide the kind of feedback help authors need to best serve users.

Slick applications like the RoboHelp Server Engine and Google Analytics offer the ability to track how many users are visiting individual pages of help content.

Help topics in MS Office applications share a common element at the bottom of the text: a feedback form. Users can tell the technical writers in Redmond exactly what improvements they'd like to see in the help. With a bit of server-side scripting and a fancy HTML form, you can build such a feedback form for your help topics. (Not much to it; in fact, most of the code is freely available on the web, if you know what to look for. The scary part is what happens after the form is enabled and you prepare to read the comments!)

These and similar tools are opening the doors to direct two-way communication between users and technical writers. When this happens, help authors will have one less excuse for providing help that simply misses the point.

Now that usage data and feedback are possible, the real question becomes...

...how do we make sense of it all, and turn that data into a help format that is user friendly and allows help authors an efficient workflow?

Time will tell.

Until then, I'll continute to drool over AIR help, dabble in home-brewed ASP.NET enhancements, and listen to more Tom Waits. ("Rain Dogs" is a killer album.)

If you enjoyed this post, check out Technical writing unchained | A custom approach to building help.