Los Angeles Tech Writer

For some of these companies, the documentation was part of a larger package of process reorganization or system implementation. The solutions company providing this service, Corporate Knowledge, Inc., of Toluca Lake, is a small but effective team consisting of the innovative CEO (who helped these client define the overall strategy using “WarRoom Facilitation”), an implementation specialist, the applications wizard, and one or more technical writer-trainers (including yours truly). In our projects, the client stakeholder was usually at vice president or global vice president level and shepherded the entire process. The department or division being revamped was fully involved and trained, and typically took final ownership of the documentation.

But in companies producing a hardware or software end product, departmental ownership of end-user documentation (meaning such things as product guides and online help) varies, and in practical terms, end-user documentation is often only one step away from orphanage. These variations exist primarily, of course, as a result of a corporation’s organizational model, but also due to organizational perception of the role end-user documentation plays in relation to the product. (Companies with an actual Technical Publications department may be more or less exempt from the subject of this article, but then again, maybe not.)

Even when a program manager owns a product’s user documentation, cooperation amongst those with a stake in documentation vision, planning and review can be hard to maintain. Two recent examples come to mind. In the first, the program manager was the foremost authority on product usability and scope, having for many years been on the user side of the business process that the software automated. She was also the primary review authority for end-user documentation, but had scarce time to contribute to documentation usability development or reviews. Similarly, the module project managers, due to workload, and who often did customer demonstrations of upcoming functionality, were severely limited in their review time. (However, one project manager bestowed an enormous gift on the documentation staff in the form of Camtasia Studio recordings of her client presentations.)

In another case, the program manager served in an administrative and leadership capacity rather than as a nuts and bolts product authority. He had enough rank in the organization to enforce, for lack of a better word, documentation development and review contributions from the various departments (quality control, marketing, developers, etc.). He was able to be a true champion of user documentation.

In fact, many organizational units have a substantial stake in ensuring high quality end-user documentation:

--Software Development. Developers and project managers strive to create the most usable product possible, and naturally want users to use it. The software applications I have recently documented have had incredible functionality, but, intending no slight to developers, I have yet to see a user interface so intuitive that every intricacy of functionality is self-evident (I don’t even know if that’s possible).

It’s important to remember that user documentation fills the gap between the obvious and the subtle. Further, documentation specialists, whether employees or contractors, very often write in a vacuum, trying to leverage initial engineering specifications against a long list of subsequent additions, a parade of software builds, and not much else. The need for developmental feedback is very high, and lack of it is a primary cause of end-user documentation not matching final product functionality.

--Marketing and Communications. The source of the majority of communications issuing forth from a company, MarCom needs to ensure that branding is consistent, and may want to see a particular level of brand enthusiasm conveyed in the documentation.

--Training Department (sometimes as part of Professional Services). Professional Services and the training department are the primary customer-facing resources after installation or upgrade. Though training materials are not the same as product release guides and online help, these departments have a large stake in ensuring that user documentation is functional; for end users, it is here that “the rubber meets the road."

--Quality Assurance. The actual role Quality Assurance should play in quality end-user documentation is probably much larger than is generally understood, and as discussed below, I submit that Quality Assurance is the most correct owner of end-user documentation.

--Customer Support. While typically not the owner of end-user documentation, documentation quality definitely impacts this service area. A Customer Support idyll would consist of pointing the customer to the exact reference, easily accessed by pressing F1. But as a symptom of poorly crafted product documentation, support representatives not fully trained on existing user documentation, or both, Customer Support often creates its own materials, posting FAQ and other home-grown documents on a Support website, quite in addition to officially versioned and released end-user help materials. (This can be rather appalling to the technical documentation staff, by the way, not to mention a MarCom nightmare).

Consider an all too common scenario: An end-user cannot easily answer his usability question through intuition, online help or other product documentation. His frustration with the product heightens exponentially with each failure. After multiple thwarted help searches, or after none at all, the customer contacts Customer Support. The support reps, who should be trained within an inch of their lives on the most current end-user documentation (with a product fluency matching the training department and project managers, in fact), are not. In reality, even with end-user documentation to hand, Customer Support staffs may try several approaches, fumble, and put the customer into the queue while performing research. Thus starts the dwindling spiral of perceived usability of a product, even though the software itself might be a marvel of workability.

So while the quality of end-user product documentation directly impacts all of the above organizational areas, in actual fact Quality Assurance has the largest theoretical stake in documentation usability. If you look at “quality” from a broad perspective, then its mission is not only to ensure that the application has no bugs (the most minimal definition of quality), but that it is intelligently designed and supremely usable. That usability most definitely extends to the clarity, thoroughness and high communication value of end-user documentation. As an aside, any support staff worth its salt would continuously monitor not only functionality issues, but also the most common documentation failures, and would provide that feedback to Quality Assurance as well, demanding documentation upgrades as part of total quality management.

In my view, therefore, end-user documentation should itself be treated as a product, not merely as an adjunct. Taken in this light, the quality of end-user documentation impacts the perceived quality of the product and the company as a whole. Consider this: We are all familiar with the almost universally-held sentiment that user instructions are useless, and it is a grim marvel to me that some of the most widely-used documentation authoring tools have gaping holes in their own help documentation. So imagine how a company could distinguish itself if it were able to boast its documentation excellence as a promotional point?

Here, then, is a rough (and ambitious) checklist to help your company take hold of its end-user documentation process so that your documentation increases not only the perceived, but the actual, value of your product and your company:

1. Decide that your end-user documentation is integral to the quality of your product, not simply an appendage.

2. If you don’t have one, pick an organizational department to become the logical owner and champion of end-user documentation. Get that manager’s unswerving agreement to be the champion (he might be a good candidate for the usability test in #4 below). Who it is will vary depending on the organization’s structure, but it should be a manager with enough authority to muster long-term cooperation amongst the stakeholders.

Which department owns end-user documentation is less important than the fact that it is definitively owned. (If your end-user documentation has a current owner, you may want to evaluate whether company growth and focus may now suggest a better one.) My favorite pick would be Quality Assurance, since it is the last stop for ensuring product excellence, and should already have increased rank and autonomy over other divisions.

3. Identify the major stakeholders and persuade them that end-user documentation affects the perceived value of the product and the company. The list should at least include the departments listed above.

--An excellent way to bring this home is to conduct an end-user survey. Find out how often your customers use the help documentation, if they know where to find it, how often it answers their questions, or whether they ignore documentation altogether, Customer Service being their first line of response. Ask them how they feel about the product’s usability. You might be very surprised at what you find.

--Another excellent way method of demonstration is for someone not intimately familiar with your product (one of your executives, say) to try to learn it using existing release and installation guides, online help and so forth. If frustration or bewilderment results, you will know with certainty what your customers are experiencing.

4. If possible, engage a qualified technical publications department manager or contractor who can analyze the current state of your materials and organize your documentation plans going forward.

5. With great ceremony, internally announce the owner and stakeholders’ new or renewed emphasis on end-user documentation as a part of your continuous improvement and/or total quality management initiative. This may require a process of cultural orientation over a period time. End-user survey results are helpful to this effort. The point is to gain cooperation and to help your organization understand the true importance of end-user documentation to the company’s overall success.

6. Go over your documentation with a fine-toothed comb. If you have QA or developer interns learning the product, conduct documentation testing that consists of the intern following the instructions contained in your documentation to see if the expected result is achieved. In actual fact, this is the review process QA should conduct prior to product documentation release.

7. Improve or revamp your documentation. Don’t forget to consider all applicable FAQ and other documents created by Customer Service.

8. Test your documentation.

9. Thoroughly train your customer service team on what the documentation contains and how to use it. Since the reps will be referring the documentation every day, in a short time they should reach fluency, and this should be the goal.

10. When you have achieved documentation excellence, or are well on your way, with great external ceremony announce it as the latest addition to your company’s continuous improvement program.

Wishing you success!