Hidden Factors of Documentation Quality -- Part 1by Bruce A. Sesnovich |
Home / Archives / Back Issues 1993 /
We all want to improve our documentation. The question is "How ?"
The first impulse of many documenters is to turn our work over to editors and graphic designers, or to form committees and develop style guidelines. All of these measures are useful, but none can assure us of quality when there are basic problems with the way we go about producing documentation.
We readily recognize specific problems with individual documents, but we often overlook more general process-related problems. If the user's guide does not match the software, this is regarded as a "doc problem." But if the reason for the mismatch is that code is being changed willy-nilly and without regard to documentation impact, then the fault lies not with the documentation, but with the development process or environment.
We tend to think of the writing team as having complete control over a document. But just as a congress person's effectiveness is limited by political considerations and by the checks and balances of the legislative process, so the efficacy of our products and documentation is a function of the environment from which they emerge.
That environment comprises not only the development process, but also people's individual skills and working relationships, as well as business priorities and corporate culture. Within this environment lurk a number of frequently-neglected factors that may strongly affect documentation quality.
I like to group these "hidden" quality factors into three categories:
The first group of factors involves people: Who they are, what they know, how they interact and how they view their roles in the process. Under this heading, I include:
Writers working at the individual contributor level, beyond keeping their technical skills current and maintaining good working relationships, are limited in what they can do about these factors. However, writing managers and project leaders must pay special attention to such matters as building ésprit de corps and ensuring that each team member feels valued and empowered.
The second class of hidden factors, Priorities and Preconditions, poses a real challenge to the quality-conscious writer. These factors include:
It is very difficult for writers to have any direct effect either on corporate culture or on the harsh competitive realities of corporate life. But by working hard, being savvy about the bottom line and taking on responsibilities that add value to their jobs, writers can exert slow, steady influence on prevailing attitudes.
I have already alluded to quality factors related to the development process. In this category, I include:
The development processes that prevail at many companies have been designed to get products out the door in a prompt and orderly fashion. In many cases, these processes do not adequately lend themselves to the needs of either documenters, or the customer.
We must not throw up our hands, declare the battle lost, and retreat to our word processors. As documentation professionals, we must educate ourselves about the process, and, where necessary, alter it. Because the process touches every document, this is an area in which a thoughtful writer can have a large impact.
Let's look in more detail at each of these "hidden" quality factors.
Politics can encroach from any direction and can rain ruin upon an allegedly cooperative effort. Problems are especially likely to arise when groups are attempting to work together across a distance, but personality clashes among co-located team members are no less destructive.
What can be done to minimize the dangers? First and foremost, managers must prevent the entrenchment of an "us-versus-them" attitude. In the case of geographically separated teams, insist that all participants come together periodically for face-to-face meetings. Phone and video conferences can help to keep everyone informed and "in synch," but they cannot replace the rapport and mutual respect that result only from personal contact.
Second, take precautions to prevent turf wars from flaring up. Make sure the charters of each group are clear and that each group is given the authority to carry through on its areas of responsibility.
I do not use the term attitude as synonymous with motivation. I take it for granted that any professional technical writer will be motivated to do the best job possible and will take pride in her work. Instead, by attitude I refer to the larger issue of the writer's perception of her role within an organization.
It is possible for writers to assume a wide range of attitudes toward their jobs and their profession. At the extremes, a writer can regard himself as either a glorified typist or else as the crafter and custodian of the corporation's most important resource -- information.
With a too-restricted view of our role, we are more likely to produce unplanned or poorly-planned documentation. We may take the path of least resistance -- uncritically accepting whatever information the developers provide and simply reformatting it for customer consumption.
If we see our jobs as limited to putting words on paper, we will ignore the possibilities offered by conceptual art or alternative media and presentation strategies -- strategies that can vastly improve the comprehension and usability of information.
A writer who is not treated as a valued contributor to a product team may become discouraged, disinterested and detached from the product and documentation development process. That writer fails to seek out members of other teams for ideas, inspiration or information. A disinterested writer neither works with human factors engineers nor makes any contribution toward a better user interface.
Neglecting their roles as customer advocates and prevented from getting involved in any decision-making affecting the product, discouraged, detached writers become an obstacle to, rather than a catalyst for, quality.
We obviously differ in our degree of familiarity with the technologies we document. It is seldom the case, however, that a writer is also a subject matter expert. To some extent, this is an immutable fact of life in an industry in which documentation specialists try to explain procedures and concepts developed by technical specialists.
A lack of technical expertise has a number of possible effects on our work. The less we know, the greater the demands we must place on engineers and developers. And lack of subject matter expertise can become a significant obstacle to clear organization -- it is exceedingly difficult to construct an accurate map when one doesn't know the territory.
There is also the issue of time. While a writer who in fact does know the territory can sit down and begin writing in short order, a writer hampered by lack of subject matter expertise must allow a lot more time for legwork in tracking down information and for forming an understanding of basic concepts.
Learning new concepts comes with the territory when you're a technical writer. We should view this as positive, as an opportunity.
The danger here lies in not recognizing that learning is one of the most difficult of human activities and that adequate time needs to be allotted for it.
When developing your documentation schedule, take account of your technical expertise in the particular area to be tackled. Consider whether the assignment involves writing for a different audience, using different tools or employing different media than you are accustomed to. Check to see if there are any pertinent courses or seminars available, either in-house or through a university or professional training agency.
One last word of caution on this point. Technical writers have deadlines to meet. Sometimes we avoid taking courses because of the time commitment involved. But this can be a false economy -- if you don't acquire your knowledge in a classroom, you will acquire it by running around, reading books on your own, and asking questions of resident experts. Be warned; this impromptu, unstructured style of learning also eats up time -- both yours and that of your consultees.
Corporate priorities usually emphasize time-to-market and place engineering and marketing ahead of "support" functions like quality assurance and documentation. This often forces writers into no-win situations. Insufficient resources, oppressive time constraints and last-minute product changes are among the most substantial roadblocks to the delivery of quality documentation.
While there is not much we can do to alter the facts of corporate life, we can make management aware of the quality trade-offs incurred in an aggressive schedule. Such arguments are especially effective if they can point to likely cost savings to be had by "doing it right the first time."
For instance, you may be able to gather information about how much each question fielded by help desk personnel costs your company, and then estimate how many such questions could be averted by documentation that is "done right," versus documentation that is produced as "a rush job." Similar cost arguments can be made about the increased number of bugs (and release notes) attendant upon a foreshortened schedule.
It is worth noting that not all costs are directly and immediately measurable. Dissatisfied and disaffected customers have a disastrous impact on the bottom line, though this impact may not manifest itself until much later, in the form of lost sales and lost reputation.
Corporate culture plays a large role in shaping a writer's attitude, and those attitudes in turn profoundly affect documentation quality.
Beyond this, corporate culture helps to define how writers are perceived and received within the corporate community. This certainly sets limits on how well writers can perform their jobs.
In a dysfunctional corporate culture, writers are basically seen as a nuisance. Their work is tolerated, but it is not regarded as important. In such an environment, the product is paramount, and documentation is perceived as an after-the-fact adjunct. Writers are not included in the development process and may not even be kept particularly well-informed of upcoming projects and changes to ongoing projects. Documentation is given little regard when schedules are developed or changed.
On the other end of the spectrum, writers are held in high regard and are well-integrated into the product team. They actively represent the concerns of the customer and contribute to the design of the product. Documentation is viewed as an integral part of the product and a crucial factor in customer satisfaction. Members of the product team enthusiastically support the documentation effort by making suggestions, contributing information and participating in documentation reviews. Writers are consulted before decisions are made to alter the product or the schedule.
There are no quick fixes for a dysfunctional corporate culture. Instead, there is a long process of consciousness raising we must promote. This is another area in which a little business savvy can help our cause. To change attitudes, we must earn respect through our work, through our contributions to the product and through our demonstrated concern for the efficiency and profitability of the business.