Technically Speaking: Tips, Techniques, and Targets to Make You a Better Writer
(As published in The Technical Writer magazine, articles by Hunter Brumfield)
Staying Afloat in a Tidal Wave of Technological Change
Your work is intense, the job complex, and the deadlines always loom. Pressure is the nature of the technical writing business, an element of the profession that is both frustrating and exciting. Thus, as a technical writer or other technical specialist, you may tend to feel sort of like a snorkeler who glides on top of the sea, only occasionally lifting your face from the water to check your progress and locate the other swimmers. Most of the time, probably, your attention is riveted on a glowing monitor and the paragraph of the moment.
Tread water for a minute, though, and look around. Have you really considered the tidal wave of technological change that has been sweeping over the products you are helping send to market? And have you thought about your own place in the scheme of things, as part of a larger team of publishing specialists in a rapidly advancing profession?
Cultivating team awareness is something that should be right at the top of the priority list of managers in documentation departments and technical publishing houses. Yet as a technical writer whose job advancement, salary, and satisfaction depend to a large degree on the quality of every aspect of the finished document, you also have a stake in how well the team works. Too, "professionalism" in the technical documentation business carries with it the ability to work well with others. Later I will describe how a company can encourage this professionalism with a strategy that meets changes, problems, and day-to-day publishing demands head-on.
First, I'd like to address the nature of technical documents in general, and how the type of document affects the way it is published. Let me state two somewhat obvious points: Usually, the more complex the product, the more has to be explained. And, in general, the more it has to be explained, the more people have to be involved in the production. The complexity of a document is one of several key factors under which documents can generally be categorized, as represented in the accompanying figure.
Product Documentation Scale
(Click image to enlarge)
Notice that as you move to the right of the scale, the documents assume various aspects that require the efforts of many individuals with specialized skills or duties. They also require much more coordination and time to produce.
In general:
"A-type" documents can be handled by one writer or translator, one editor, and one illustrator. They are usually only a page or two in length, designed to explain how the device works as simply as possible, and neither the manufacturer nor the purchaser considers the manual as an important part of the product package. This type of document must be well executed, but can be produced cheaply and quickly. Like their products, the instructions are generally of a throw-away nature. It is not necessary for anyone involved in producing the document to be a specialist in that product.
Time required for publication (to printing-ready stage): from two days to two weeks.
In general:
"B-type" documents require one or more writers (and/or translators), one or more technical checkers, a photographer, an illustrator, a designer, and a scheduler/coordinator. Some of these jobs can be done by the same individual. It helps if the writer has some experience with operating or using the product, but it is not essential.
These documents are larger in size — from 18 to somewhat over 100 pages. They are primarily reference materials, meant mainly to supplement the product with information considered important to its use. However, the typical user would be expected to refer to them only occasionally.
In the case of consumer products, the documentation would be considered somewhat important to the success of product use and, as a consequence, to sales. While product reviewers in consumer magazines and other media would likely make a passing reference to the quality of the instructions (particularly if they were bad), the typical buyer would probably not think to look at the user manual in advance. Despite that, satisfaction with the product likely would be enhanced (or hurt) by the quality of the documentation.
Time required for publication from two weeks to two months.
In general:
"C-type" documents require a staff of specialized writers and/or translators, one or more editors, a photographer and photographer's assistant, an illustrator and several draftpersons, a designer, one or more technical checkers, one or more product engineers, a coordinator, and an overall project manager. Most duties are of a specialized nature.
Page counts can range well into the hundreds of pages, often across several volumes. Users depend heavily on the information, depending on the documents for training and/or frequent reference.
These documents have direct influence on the market success of the product. A buyer is likely to look with considerable interest at the instructions before purchase. The documents must not only be highly usable and accurate, but reflect the status of the product (that is, if the product costs several millions of yen or thousands of dollars, its user manual and support documents cannot look cheaply done). Reviewers would treat documentation as a separate issue and could condemn a product solely on the basis of a badly prepared user guide.
CD ROM or Internet versions of the documents, as well as online training programs would be available for many if not most "C-type" products.
Time required for publication: from two to six months.
Each type of publication presents its own particular challenge.
"A's" must be produced cheaply and quickly. These products are like bottle rockets. They have a short fuse, quickly shoot to a peak, and then pop with a small report and a scatter of smoking paper. The market wizards judge their lives in terms of months and their profit margins in terms of a few hundred yen or several dollars, from large-volume sales. There is no time or money to be wasted getting these products aloft. And the fewer people involved, the better.
"B's" also have a relatively short life expectancy, with new models quickly supplanting last season's. Yet somewhat more attention can be spent on all aspects of the product, including the documentation. Here, other marketing angles, such as the product's status and sophistication, assume importance. The user guide must be on the same level. A larger documentation team and more time are required.
"C's" have a considerably longer development phase and subsequent product life. The users are expected to be familiar with the product or to be able to obtain adequate training. The documentation is an essential part of the package, and requires the careful attention of a solid team of specialized writers/translators, editors, technical checkers, and various support staff. Software upgrades, typically downloadable from the Internet, are an important aspect of continued use of many of these products.
• Responding to changing technology
Stop and think about this for a moment: How long ago would the idea of needing an instruction manual for a telephone have seemed ridiculous? Or, for that matter, that your mechanic would need to be as handy with a digital analyzer as he is with a tire gauge? Thanks to high-speed microchips and, more recently, laser, plasma display and communications technology, many long-stagnant products have been catapulted through a sudden evolution in usefulness and complexity and hundreds of other fantastic new devices have been created — creating, as well, a healthy demand for the skills of technical writers, editors, and other publishing specialists.
So how does a technical publishing company (or corporate documentation department) respond to these changes? Not by doing things the "tried-and-true ways" of 20 or even 10 years ago. If your firm/department has not made major adjustments to the new developments in technology (including publishing technology) within just the past five years then you are still back in the technical Dark Ages.
There are a number of areas where these adjustments can be made. I wish to spend the remainder of this article looking at the most important part of the entire operation: the professional technical documentation specialist. I use this rather ponderous title because I want to include virtually everyone involved in the technical publishing effort.
• Developing the team approach
All these changes have resulted in a stronger emphasis on the role of technical documentation specialists as a member of a team, rather than as a lone wolf. The increasing complexity of the typical document today itself requires specialization but also far more coordination and cooperation between technical team members. A well run operation can do this by 1) encouraging team awareness, 2) inculcating in each member a clear understanding of the work and requirements of others, 3) systematically improving the skills of the team, 4) promoting in each member an appreciation that he or she is contributing something important to the final results, and 5) directly rewarding the successes and analyzing the failures of the group.
Here are the key elements of the Team Approach, which can be applied with success in smaller companies (where networking takes the place of actual company staff) as well as the very largest.
Identification
Members should feel like they are part of a clearly defined documentation team. The designation of each staff member should be made in writing and posted or distributed a few days in advance of the first meeting. The assignment can be either to a "team" (being called, for instance, the "Blue Team") or to a particular job (and thus take on the name of the product model). Putting it in writing is the first step in formalizing the team and clearly defines team membership.
Organization
At least one general meeting should be held at the start of the project to orient the team on the new work, and to acquaint everyone on who will be working together, especially in the case of new or external staff, when freelancers or consultants are brought in. This first meeting sets the tone of the project and so should be well organized and have a tight agenda. (Of course, this goes for all meetings.)
Understanding
At this first meeting, the team manager should generally explain the nature of the job and clearly state the responsibilities of each person. A brief outline of any new technology or special features of the product should be given, usually by one of the project engineers. Questions should be solicited and clearly answered. An important job of the project manager during this and every meeting is to diplomatically keep the discussion directly on the points of the agenda.
Detailed, integrated scheduling
A detailed schedule should be distributed, discussed, and modified where necessary. The important factors here are to: 1) give each member enough time to do his or her job well but within a clearly set time frame, 2) establish intermediate deadlines that must be met to keep the project on schedule, and 3) integrate the many facets of the project so that no unnecessary delays or bottlenecks occur.
The schedule should be realistic from the very start. However, if it must be changed later, each team member should be given a copy of the new schedule.
Clearly attainable goals
In the rushed business of technical publishing, meeting a calendar deadline is often treated as the primary goal. Yet there are a number of other targets that also must be met. These include accuracy, clarity, consistency of style, quality of writing and illustrating, thoroughness of the explanation, and so on. The old saw in technical publishing is no less true today: "You can have it on time, cheaply, and with no mistakes - pick two of the three..."
Of course, it is the nature of good business management to push the staff to their best limit - that is, to the limit that requires people to work with steady efficiency but with high quality. It is also the nature of the business beast to try to push them a little, or a lot, more. This is counter-productive in the long run, however, leading to quality control problems, exhausted and dissatisfied employees, and excessive overtime pay.
A good manager knows what the staff can do, sets goals that are reachable, and can skillfully organize company and outside resources to better accomplish those goals.
Encouragement and feedback
All people need encouragement and feedback from others about the job they are doing. To put it in MBA-speak, the team approach helps to structuralize the feedback mechanism. In other words, people are more likely to give you a pat on the back for your good work if you are part of their team. They are also more likely to give you useful advice and helpful criticism if they see it as helping the team. In an office of lone wolves, on the other hand, people are more likely to jealously guard their skills, rather than share them with others.
While skills usually are taught "downward" from the more-skilled to the lesser-skilled, the act of teaching itself helps to instruct the teacher, since he or she usually gets asked a lot of good questions that require thoughtful consideration and often a little covert homework. Too, fresher minds can often come up with new and better ways to do the same thing. The teaching, then, often goes both ways and the entire team benefits.
Appraisal and reward
All through the project there should be regular appraisals by senior staff of the work being done, not as some angry or impatient search for flaws, but to give the team members a way of assessing the quality of their work on a regular basis and to catch systematic errors early. Regular appraisals also help keep the project on schedule.
Rewards can be given in a variety of ways. The best reward, as many good managers have found, is a smile and brief public expression of meaningful praise. Later, exemplary work should be reflected more discreetly in the size of the bonus or extra holiday time, along with a private comment that the good work was remembered and appreciated.
For the team at large, rewards can take the form of a day off from work, a company-sponsored dinner, or a special company outing.
Turning over the rocks
Finally, there should be a concerted effort to bring into the open any errors, bad decisions, scheduling problems, or other difficulties that may have occurred during the life of the project. This includes personality clashes and anything else that may have hurt the performance of the group. While this can cause some painful moments, it's better for the rocks to be turned over, so to speak, to shine some light on the things lurking there. Keeping problems covered up only means they will probably occur again with the next project.
One other good thing about the Team Approach is that it can be highly formalized and tightly organized, or very informal - whatever seems most appropriate to your company and staff. The important thing is that you learn to change and grow along with the changes that have been washing over your company and your job while you struggle to get that next page or illustration done... well crafted, with no mistakes, and RIGHT NOW!
Copyright © The Technical Writer Magazine. All rights reserved.