Technical Writing: A Workflow-Based User Manual

I recently took part in a discussion with some fellow tech writers about the proper way to create written product end-user help. The task was how to help consumers learn how to use the product they had just bought. The catch was that the product was complex, had many features, and was going to end up being about 500 pages long.

While many of the writers chimed in by touting age-old rote methodologies for developing product documentation, I eventually asked the question, "Do we even need to use written content for our users' help?" After this comment, we went through some discussion on the merits of creating help not in written form, but perhaps as help in video format. In the end, we determined the user help needed to be delivered in writing for legal purposes.

That decided, we still had the issue of how to organize 500 pages' worth of help content in an organized fashion. My comments in the following sections basically summed up what we had decided upon.

Searchable PDF Document

A long-form 500-page doc is good for users who are used to working with a table of contents in a printed doc, or searching a PDF for a keyword. Go ahead and make docs like this for this first kind of audience. Otherwise, there are two additional ways to address the issue.

Workflow-Based Help Content

The next method is to create new docs that support common workflows. For example if you have a nurse using a medical device, and their role dictates that they are allowed by law to perform only certain tasks on the device's software/user interface, then develop documentation specifically purposed to address their workflow. This can be delivered to the user usually as a printed workbook, a short job guide, or as a PDF.

Context-Sensitive End-User Help

The last common way to address this builds on workflow-based content. Try providing context-sensitive end-user help that can be invoked by clicking a help button on the actual application screen in which the user is currently working. The help that pops up has only to do with that screen's features, and thus eliminate the need to sift through an entire manual. If they wish, the user can click on to other links if that screen's help isn't what they need.

Implementing context-sensitive Help requires some collaboration with the application engineers, as they will need to create code that will cause this context-sensitive help to pop up. The engineers also need to be able to find a way to easily deploy Help content updates, should you find areas in your Help content that require updating, or are inaccurate and require correction.

In creating user documentation - and deploying it - use what works for the audience you have in mind.