Hidden Factors of Documentation Quality -- Part IIby Bruce A. Sesnovich |
Home / Archives / Back Issues 1994 /
The importance of an information plan (or "doc plan," in the common parlance) is so widely recognized as to hardly require mention. Anyone who has ever attempted to drive in the metropolitan Boston area immediately recognizes the difficulty of navigating through paths that simply "evolved," as opposed to navigating through those that were set on a grid by a city planner.
The existence of a doc plan, however, means very little in and of itself. Documentation "plans" can be constructed after the fact, or can be based on documentation developed for other, possibly marginally related projects.
Have you ever had the experience of writing a detailed doc plan, only to discover that your finished product bore almost no resemblance to the manual you planned? If you find this happens regularly, you are probably not writing useful plans.
Most commercial technical documentation is written in a production or an R&D environment. Thus, the documentation is developed in parallel with the product. Therein lies a fundamental frustration of our profession -- we are continually trying to hit a moving target. A woman I used to work with had a sign on her cubicle that read: "Documentation work is like trying to change the tire on a moving car."
This parallel development of documentation and product ensures that the documentation will have emergent properties -- that is, elements and aspects that cannot be predicted because they take shape as a result of the development process. Mind you, the presence of some emergent properties is a sign of a healthy process. The alternative is a stolid design-to-spec mentality that takes no account of new information, including feedback from customers.
To the extent that features and properties cannot be predicted, there would seem to be little sense in detailed content planning at the start of the writing process. It is to no point to labor arduously to produce a boilerplate plan merely to satisfy a corporate requirement. The trick is to produce a plan conducive to quality documentation. But what kind of plan does that?
I submit to you not that our plans tend to be too detailed, but that they focus on the wrong details. Very early in the writing process, when many aspects of the product are unknown or subject to change, the focus of planning should he not on product features, but on customer needs.
Any completed plan represents a number of decisions about the documentation. But we seldom seem to ask ourselves what criteria to use as a basis for making those decisions. I propose that the criteria ought to come from research into our customers' information requirements.
Too often, our "research" is short-circuited before it even begins. This happens when the research starts with the question: "How was this type of manual clone before?" -- or even -- "Where can I steal this documentation from?" Now, this can be an eminently reasonable and time-saving approach; creative plagiarism is in the best tradition of technical writing.
But we ought to be wary of the large-scale appropriation of doc and doc plans -- it presumes that documentation decisions made by someone else at some other time are applicable now, to our project and our customers. And it ain't necessarily so.
In general, a better starting point for research is to speak with marketing and human factors engineering personnel about who will be using the product and how. Certainly, this should have some bearing on how information gets presented.
Product and task analyses should be conducted where appropriate. Writers should familiarize themselves with pertinent human factors studies and papers published by the ACM and the STC. Depending on the product, it may make sense to arrange for direct meetings of writers with customers.
To short-circuit this research is to short-change our readers.
To summarize, documentation planning should begin with a formal customer information needs assessment. The initial doc plan should be based on the results of this assessment and should not get excessively hogged down in details that are likely to change as the product emerges.
Let's be honest; coordination and teamwork are often paid considerable lip service. Teamwork frequently is touted as an important corporate value or even listed as a factor on job reviews.
In practice, however, we writers tend to take on a more-or-less circumscribed function within the product team. Part of this is due to corporate culture or the lack of a clear role for writers.
However, part of the problem is that we just don't take the initiative as frequently as we should. For instance, writers should seek out marketing folks in the early stages of a project. We should make sure we understand how the product is being positioned and what optional features are available. Marketing should review the information plan with an eye to improving how well it meets the needs of the product and the customer.
As another case in point, writers should attend product design reviews, serving alongside human factors engineers as customer advocates when decisions are being made that affect product usability.
If your company has an education and training department, you should seek the advice and collaboration of the people who develop the courses and training materials. Not only might you save time and effort by leveraging each other's work, but the efficacy of both your documentation and training material will be enhanced by greater co-ordination.
Information about a product can be built into the product itself, it can be included in an online help message, or it can be written into a reference manual. For each piece of information about the product, the decision of where to put it depends on how the product is used and by whom. Correct decisions lead to ease-of-use. Bad decisions lead to confused customers.
A good writer -- understanding on the one hand how to structure information and, on the other hand, the nature of the product and needs of customers -- can play an important role in the development of the information and the product. But to do this, we need to get involved early in the project and we need to be supported and included by the rest of the team.
A lack of a clear understanding of the writer's role often causes writers to get involved much too late in the product development process. The same lack of understanding on the part of other members of the product development team leads to their failure to properly support the information design effort.
As the writer sits at her desk, fingers arched above her keyboard, ready to explain, analyze and describe; the future recipients of the writer's jewel-boxed, slip-cased or shrink-wrapped documentation are no-where in sight. The hardware or software being documented is usually nearby -- it may be running in the lab or on the writer's desktop. Specifications and white papers describing the product are piled up on the writer's desk. Phone extensions of various developers, scribbled on post-it notes, adorn the writer's wall and computer screen.
But the ultimate consumers of the documentation and the technology are all-too-often little more than shadowy figures in the writer's imagination-distant and anonymous "end-users," "administrators" and "programmers." Under these circumstances, it is not only understandable but almost inevitable when the writer loses sight of the customer and winds up focusing his attention myopically on the product instead. And focusing on the product leads to confusing, product-oriented documentation.
The only way to counteract this tendency is for us to understand the people we are writing for and what they do in their day-to-day work. This kind of active understanding requires research and conscious effort. The documentation development process should take this into account by building into the schedule time and opportunity for writers to get to know customers.
I hope this brief summary of some of the more obscure dramatis personae on the stage of technical documentation development will help you to look with fresh eyes at writing problems you may encounter. Psychologists often say that being aware of a problem is the first step in solving it. That aphorism applies as well in our sphere.
Taking account of these hidden quality factors will make demands on our skills and abilities. It will challenge us to learn, to grow and to adopt new, more expansive roles. In many cases, it will require that we examine and change the processes by which we produce documentation.
It is high time to change the writing process and the writer's role. Today's multimedia and hypermedia systems call out for approaches different from those that Gutenberg engendered. It is time to stop thinking of ourselves as manual writers and to start thinking of ourselves as information designers.
The role of information designer places special emphasis on understanding the needs of the customer, doing the up-front planning and research needed to address those needs, and working closely with other team members to bring the resulting plans to fruition. The role also requires us to learn to work with new tools in new media, to develop a good business sense and to strive to increase our worth to our employers.
It is to be hoped that adopting a new role of increased responsibility and challenge will improve our attitudes toward our jobs. This change in attitude both leads to, and is reinforced by, greater achievement. As we begin to participate more fully in product development and design, and as we start to gain recognition for our contributions in this area, our stature as individuals, as well as the stature of our profession, can't help but be enhanced.
The author gratefully recognizes the information and interface specialists, past and present, of Sun Microsystems' Chelmsford campus, whose ideas form the basis of this article. Special thanks to John Sundman for the vision of "Information Architecture"; and to Elaine Welch, Dave Damkoehler, and Michael Seif for their inspiration, consultation, commiseration and friendship.