Create software user assistance from system specifications

Posted 21 January 2011 by

User assistance needs to match software as it was built, not how it was envisioned. It takes time to create user assistance. A company wants to see a return on investment as soon as the software is complete.

Ay, there’s the rub. (—Hamlet)

This means the first draft of user assistance for a product’s initial release should exist by alpha testing. It must exist by beta testing. This is a good thing, as all user assistance needs to undergo quality assurance as much as the software.

This requires the writer to be “in the loop” with system design documentation and change orders.

Iron Mountain SecureSync

SecureSync from Iron Mountain

SecureSync from Iron Mountain

From about 2001 to 2004, I was involved in creating the first release of user assistance for SecureSync® from Iron Mountain®. Customers use this online product to manage their off-site electronic media storage account. They can keep a record of what media is stored, request the return of media, store their disaster recovery plan, add and remove people on the account, and declare a disaster recovery emergency. The user assistance was web-based, created using RoboHelp®.

User assistance content

The user assistance in the system help provided three basic types of information:

  • Background and general information. Define the product and its uses.
  • Task information. Instruct how to perform specific tasks.
  • Glossary, screen, and control information. Along with definitions, this information gave the required formats for screen controls and data files entered into the system.

Later in this post is an explanation of where I would recommend things go today.

Work with the system analysts

Frequently the job of a technical writer (or a system analyst) feels like this:

It’s not my job to run the train; the whistle I can’t blow.
It’s not my job to tell how far the train’s allowed to go.
It’s not my job to let off steam, nor even clang the bell.
But let the damned thing jump the tracks, and see who catches hell!

A writer does not decide what features the software includes. Input to the user interface is not a given, although some projects seek it.

The success of the writer hangs on the quality of the system specification documents made available to the writer. This means becoming friends with the system analysts. Being a friend means helping them do their job, because you cannot do your job without them.

Problem identification has happen when I ask the innocent question, “So how does this work with that other thing, given this?” Sometimes I find out another piece of information that reconciles everything. Sometimes I walked with the first analyst over to the cubicle of a second analyst to reconcile it. My questions have resulted in a change in specifications, working on SecureSync and while working elsewhere.

In general, the use cases provided me the basis of defining each software task. I used the screen specifications to give the format of data inputs (length, whether required, numeric or alphanumeric).

Just as my questions sometimes lead to improvements in the specifications, asking an analyst to review information for user assistance led to improvements, too. When working from specifications, it is possible to put the emphasis on the wrong place.

Change orders

There are changes to system specifications. Always. The question is whether a change results in changes to the user assistance. When creating the user assistance from the specifications, rather than a finished product, this question becomes critical to the success of the project.

Changing the version of SQL probably does not change the user interface. Changing from a screen with a page full of inputs to a wizard with multiple pages would change the user interface, by definition.

What worked the best on this project was being on the email list for all changes, so I had awareness. My manager and I could quickly dismiss some changes while seeing the need to incorporate others. Working with the analysts helped on those changes in a gray area, or if you saw what looked like a benign-looking change on the surface that might affect something else downstream.

Quality assurance

The analysts can do this, but they already know how things work. I found the best quality assurance work for the user assistance came from people from support center. They understand the people who will use the product.

At any rate, when someone is testing a user scenario, that person should verify the correctness of the procedure of what is in the system help.

Differences today

Today, I would recommend only placing the task descriptions directly into the system help. When someone has a problem, they want the solution quickly, and without lots of distractions. Give it to them without the frills. You do not need a screen shot when the screen is in front of them.

The other forms of user assistance mostly go in other places, with the possible exception of the glossary

My recommendation would be to blog the background information on a public site. This serves as a sales tool as well as user assistance.

My recommendation for the information about the screen controls would be to redo the user interface so it includes this information. Do not create separate help topics for this. This means that I, as the writer, need to have input on the user interface.

Some of the longer screens may need to become wizards. It may mean having help text display when pointing the mouse at a button (although this can have accessibility issues). But, you have happier users if the assistance is there for them on the screen to help them do the job, not hiding details in the help.

Personally, I dislike including glossary definitions as hidden text that shows in-line when pointing a mouse at a term, or some other variation on this theme. This breaks the reading flow for me. I can only imagine what it does to a person using a screen reader, assuming the accessibility of this solution (which I doubt). This is a case where I would work with the team to find the best solution for the project, such as a creative use of the HTML/XHTML <abbr> tag.

Post Details

Leave a Reply

Page optimized by WP Minify WordPress Plugin