Two Stories About How to Write Help

by Tom Johnson on May 2, 2009
categories: technical-writing

The mindset in which most technical communicators write help is sometimes fundamentally flawed. Consider the following two stories and the different approaches and mindsets each writer takes toward the project.

Story #1

Because the ACME project team is building a complex software application for a large number of users, they decide to bring in a technical writer to provide help materials on how to use the application. The technical writer works side by side with developers for months as the team builds the application. During this time, the technical writer carefully gathers information and arranges it in task-based topics in the help.

The day of the application's release finally comes. The technical writer delivers his help to the developers, and they include the help file in the application and release everything into production. Now that the job is finished, the technical writer starts working on help materials for another project.

Kim, one of the users of the new ACME software application, starts exploring the application and has a few questions. She searches for answers in the help but finds only part of the information she needs.

After clicking around and trying keyword variations with no success, she calls the help desk for more information. The help desk, generally clueless, escalates the questions back to the project team. The business analyst on the project team provides phone support to the user and realizes the user has a special situation the team didn't consider. The business analyst explains a workaround.

As the days go by, Kim is just one of many users who follow a similar pattern. Due to unique work processes and unanticipated uses, other users aren't finding all their answers in the help either. Some of them have the same problem as Kim. They turn to tech support and Kim for answers because they can't find answers in the help.

As time passes, tech support and the business analyst start to accrue a sizable number of incidents, resolutions, workarounds, quirks, and bugs. After 3 months, the developers decide to release an update to the application. A week before the release, they call back the technical writer, who hasn't thought much about ACME since its release, to make a few updates to the help. The technical writer asks the developers what has changed and makes appropriate updates to the help. The help is then packaged with the application again and version 2.0 is released.

However, this time when users have questions, they remember their previous experience with the help and decide to skip it altogether. They know their answers won't be there, and they call the support center immediately when they have questions.

One day, looking over hit statistics, the project manager says to the technical writer, "No one is accessing the help."

"Hmmm," the technical writer says.

"Maybe the application is so intuitive they don't need it," the technical writer says. But the technical writer knows better.

Feeling that no one reads or wants the help he creates, the technical writer places less importance on his work. He gets sloppy and a little careless. Eventually, the technical writer sees his role as insignificant to the project's success.

When version 3.0 is released, the project manager forgets to tell the technical writer about the changes that need to be made to the help. The help is now grossly out of date and inaccurate. As new users explore the help and discover this, they close the help window for good, never returning to it again.

Story #2

Because the ACME project team realizes they have a complex application, they call in a technical writer to provide instructions and help materials for the users. The technical writer creates the help as best he can based on research he gathers from the project team, users, test requirements, and other specs.

Long before the application's release, the technical writer secures a location for his help files separate from the application code, in a place he can update on the fly, and then he gives the developers a link pointing to the online help file.

After the release, Kim, a user, starts to explore the application and turns to the help for answers to questions. Because her process differs from what the technical writer anticipated, the help doesn't full address her situation. She finds part of her answers and calls support for help. Support escalates the problem back to the project team, and the business analyst takes care of Kim's situation by explaining a workaround.

The technical writer is subscribed to e-mail alerts with each support center incident. He finds out what the problem was, talks to the business analyst about it (requesting to be CC'd with each user interaction), and adds the situation and solution to the help materials. He then publishes an immediate update to the help.

Several other users have problems similar to Kim's. They turn to the help and find the topics that the technical writer has just added. Joe, however, has a question not in the help. He raises the question during training, which happens to be conducted by the technical writer. After the training, the technical writer adds Joe's question and the resolution to the help. He sends Joe an email with a link to the help topic containing the newly added explanation.

A few other users need help and search the help for answers. They're surprised to see such specific information in the help file. However, because they're in South America and don't follow the same process, they have questions on how the system could be used to meet their needs. The business analyst copies the technical writer in her reply, and the technical writer updates the help based on their questions.

Each time the technical writer updates the help, he publishes the update so that it is immediately live. The help material is single-sourced, so publishing an update to the online help also outputs to PDF as well, updating the manuals. The technical writer does not have to manually edit the print deliverables. It is all single-click publishing, run on a daily build script.

As more users turn to the help, their confidence builds because it actually contains answers to their questions. The technical writer receives feedback from multiple customers about how useful the help materials are. As a result, the project manager and business analyst ensure the technical writer is included in all meetings and copied or made aware of all workarounds, issues, bugs, and other quirks in the system. Each time the technical writer learns of some new issue, he adds it to the help.

Looking back, on the day of the release of the first version of the software, the help contained only 75 topics. It now contains 140 topics. Users continue to write the project manager to express their satisfaction with the help. The technical writer both feels and knows that he has a valuable place in the project team. When versions 2 and 3 are released, users access the help file with confidence, fully expecting to find the answer to their questions.

Conclusion

What's different about these two examples? In the first example, the technical writer operated under the assumption that he could produce complete documentation at the time of the release. His help was trapped with the application, unable to be updated except at version releases. At the time of the release, the technical writer felt he was done with the project.

In the second example, the technical writer operated under the assumption that he could not learn every possible scenario, business context, purpose, and use of the application before the release. He tried his best to provide complete documentation but realized that the help had to be a living, breathing document that would continue to grow from the release date.

In fact, the release of the application marked only the start of a multi-phase process in creating the help. The technical writer continued to add and refine and supplement the existing help with all the information users needed as time went by.

In sum, one saw the application release as the end. The other, as the beginning.