RSS 
Email 
Twitter
FacebookTwo Stories About How to Write Help
May 2nd, 2009 | Posted in Technical Writing 11 Comments »
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.
Very nice post Tom, and you make a good point.
But in my experience, while many help authors would love to work in the way you describe in story #2, there are external factors that come into play making them work in the way you describe in story #1. Those factors could be a lack of recognition of the contribution they could make; limited resources or budget; or simply the fact that they were hired as contractors for a short period of time and did the best job they possibly could until their employment came to an end. If they were given the choice between the scenarios you describe I don’t think many help authors would deliberately choose the story #1 methodology as being preferable to that in story #2.
David, you make a good point, especially for people who have short-term contracts to complete a job. However, in my experience, many of the perceived strictures and limitations are either loosely defined by the department and then passively accepted by the technical writer, or are conventions the technical writer follows out of habit. For example, no one automatically sets you up with an incident report list from the support center. Nor does the project manager automatically include or CC the tech writer in all meetings and replies to clients. Unless the tech writer goes out of his or her way to define the rules for how he or she wants to work, the tech writer will fall into convention, i.e., story #1.
Tom,
1. I’m not a help author, so I don’t know what “publish the update” means in Story #2, pgf 7. Does it include updating the application with a new set of help files? Is this a capability that a small (<$10M annual sales) sw dev company can provide to its customers? If not, how does the smaller company accomplish this?
2. Is it realistic to assume that the company’s tech writer is the company expert about how customers should be using the product? Is there a “product manager” or “product architect” in the company who is more of an expert in the product’s subject matter domain and marketplace? Would that person (rather than the tech writer) also have authored a product plan or specification that describes the product’s purpose, profiles of expected users, expected workflow(s) for using the product, etc.? The point here is, the more fully planned the product release is, the more successful will be the product’s reception by customers.
3. How often to “publish the update” to customers? Are they notified in advance? Does it occur according to some schedule? How often is too often?
Thanks for your post.
//Paul
Paul, thanks for commenting.
Re 1., “publish the update” means to update the help deliverables immediately. In smaller organizations, where there is less bureaucracy about change release procedures, it’s much simpler. The key, however, is to keep the help separate from the application code. In my situation, most of my help goes to an internal audience behind a firewall. We also have SharePoint. I use a file document repository on SharePoint as the location for my help. This allows me to update it on the fly. I give a link to the developer that points to my help on SharePoint. Soon we’ll move to single sign on, and then I may push for a separate help server for all our deliverables. The single sign on solves the problem of secondary logins when logged-in users jump from server to server.
Re 2, sure you would think the project manager gathering the requirements would be omniscient about customer needs, but unless you pull from all customers, there will be gaps. Think about how 300 people use Microsoft Word and Photoshop. If you pull requirements from a dozen people, how representative will their needs be of the whole? You can imagine that the way you or I would use Photoshop and Word will differ from the way a financial analyst or a high school student might use the apps. It’s impossible to know all the ways apps will be used. But yeah, the more you learn beforehand, the better.
(By the way, the fact that software goes through multiple versions proves that no matter how good of a requirements gatherer you are, customers will want something more or something different.)
Re 3., Printed matter becomes problematic here, but if you update the online help, you don’t need to notify customers. Your paper manuals might benefit from a timestamp. In my experience, most people search for their answers. They may download a manual becomes it feels like a security blanket, but it’s the online help that they search.
Both the stories you have described are very much true. I guess the first one happens very often than the second story. When technical writers show indifference updating or implementing user feedback in the help files then software developers take this responsibility, resulting cut back of technical writers role.
A nice post, Tom!
I do have a query though – how does the writer of scenario#2 deal with translations? Are the updates made to only the English version?
Translations … right. Here it becomes impractical. I would recommend keeping the primary help (usually English) updated and only worrying about updating the translated versions at application release intervals.
Translatations – yeah, an easier way to handle that would be to backlog it up for the next application release.
I have seen these two stories acted out in every single technical writing gig I have had. Each time, the second scenario (continuous updates, technical writer being notified of user issues) is proposed, but never actually takes place.
From a project management point of view, PM’s rarely let a technical writer continue working past release date. They don’t want to treat documentation as a continuous expense but as a one-time expense. Instead, PM’s assign the TW to another project. The time for revising comes before the next software release. I’m not defending this practice, merely pointing out that it may be unrealistic to think that PMs will budget for that.
As a practical matter, I’ve gotten around the problem by 1)pointing local help to a URL and getting permission to update on an as-needed basis, 2)getting to know support people very well, and 3)resigning myself to fixing these “user topics” in the update.
Sorry, more.
I think your ability to get feedback depends from job to job. Depending on the scale of your product, you may have a big enough customer base that the technical writer stays at work the whole time. That rarely happened for me though.
Also change management is a big issue, even for web only applications. PM’s want the ability to decide how many updates the TW provides. Perhaps the point I’m getting at is that when the TW proposes something, it’s generally not going to be listened to. But when Support is proposing that the TW do some updates, PM is more likely to listen and act.
In my most recent job, everything went into an Entrack bug tracker, including support issues and feature requests. In fact, often customers entered their own tickets–but our customers are probably atypical (they are sysadmins).
As a result, I got to see all the outstanding issues, but things had to be reported and assigned to me first. This is not ideal; for example, usability issues are never reported–or more importantly, they are rejected by developers or Project managers because they are “user error issues.” As a technical writer I can anticipate a lot of user issues that a bug report will only hint at. But it’s a start.
Like I said, I’m basically agreed that the 2nd story is best case scenario, but I wanted to give insights into what it almost never occurs.
Here’s the key question: is bug-driven documentation going to produce good results? Why or why not?