Technically Speaking: Tips, Techniques, and Targets to Make You a Better Writer
(As published in The Technical Writer magazine, articles by Hunter Brumfield)
An End to 'Seat-of-the-Pants' Technical Writing
You'd probably blanch at the thought of getting into an airplane piloted by someone who simply cranked up the engines and flew off without meticulously going down the usual instrument checklist, determining the weather conditions, consulting a map, and so on.
Such foolheartiness is referred to as "seat-of-the-pants" flying, for which barnstormers and bush pilots in their balsa-and-canvas biplanes were famous long ago. Fatally so, as it sometimes turned out. For a flyer, not noticing a near-empty fuel tank or flying into the maw of a hurricane are mistakes usually made only one time.
Yet what about the technical writer who begins a new manual without the help of a checklist to ensure that the takeoff, trip, and landing all go smoothly? Or what about the manager who thinks it's enough to give takeoff permission and then walks away from the control tower?
When it comes to much technical writing, we're not talking about an itty-bitty, two-seater biplane either, but a huge, complicated jet airliner. One that is almost guaranteed along the way to encounter bad weather, misoperating parts, maybe a frantic passenger or two, and an airborne traffic jam over O'Hara.
Just like the professional pilot, the professional writer should have his own set of checklists he consults at various stages in the document production cycle. Of course, the ultimate checklist is the document outline, which provides a series of guiding beacons from the time the word processor is turned on to the moment the finished manuscript is dropped on the editor's desk. But it's not the only such list.
For the typical electronic product user manual, there are basically four separate checklists. All involve the writer's responsibilities, but it helps if you break the lists down into separate categories of writing, designing, producing, and managing.
These are the checklist questions (and their reasons) the writer should ask him or herself.
• Writing Checklist
Before:
Make sure you answer these questions before starting writing.
1. Is there adequate support documentation for the product?
These documents include the engineering specs, previous English manuals written for earlier models (if any), and the original Japanese manual. One or two reference books on the technology are usually helpful, as are any articles that have appeared in English trade magazines. Moreover, a couple of manuals from similar or the same products manufactured by other companies are worth analyzing to see what the "other side" is doing - both good and bad. If you're a freelancer, or working for a company other than the manufacturer, don't be shy to ask if they have samples of other manuals or reference books you can use. They should think of that themselves and supply these resources to you as a standard practice.
2. Is a working prototype available?
The lack of a working prototype can be one of the biggest writing obstacles, as engineers struggle to put the finishing technical touches on a machine that writers must meanwhile imagine how to operate - sort of the way kids play fantasy "air guitars." Writing goes much smoother, especially in the case of programmable equipment such as ECRs (electronic cash registers), PCs (programmable controllers), or mobile phones if you are able to push the buttons yourself during the writing.
Unfortunately, the much-awaited moment of the prototype's arrival usually introduces a new set of problems since often the thing doesn't work the way the engineering specs say it should. The result is frustration and confusion: are you pushing the buttons in the wrong sequence, are the specifications faulty, or is the machine to blame? At times the answer can be all three, to be corrected only after much time passes. Such are the sublime joys of helping parent advanced technology. Eventually the bugs are flushed out, and your writing can be finalized.
3. Do I understand the technology well enough? (Or, if not, is there an expert I can consult?)
Unless you are working on something extremely advanced, like booster rockets for the first Japanese space station, you probably can understand the technology behind most consumer and manufacturing equipment. Remember, if you are mystified by it, so will be the user. Thus, in some ways, being dumb about a device can be a partial qualification for writing the manual for it. You'll be the specialist on the questions to ask - those things that just don't make sense to you. If you do your job well, you'll know the device's operation sufficiently well by the time you finish, and you will have been able to identify the likely points of confusion and steer the user around them.
Still, even after you've done your homework, you'll almost certainly have occasional problems understanding certain technical aspects, and thus should hold one or several meetings with the product engineers. You should also have a phone number handy for quick answers to questions that may come up. An unofficial but highly important part of the testing of new equipment involves what the manual writer discovers is faulty or problematic that wasn't spotted by the development team. So your calls and questions are generally welcome. But don't bother them with questions that can be answered by a more thorough reading of the engineering specs. The engineers' deadlines may be even more difficult to meet than yours!
4. Do I have a clear idea who the typical user will be?
If this question sounds familiar, it may be because you remember one of the banners I was waving two years ago in a critique of a copier manual I did for The Technical Writer. I described a writer who pasted a picture of a secretary on the wall over his word pro to remind him who he was writing for. Truth is, that technical writer was me, and I haven't done it since I moved away from a convenient wall. Nonetheless, the rule still stands: Know who you are writing for, and keep thinking about that person from the very first to the very last page. "Who?" is one of the key questions you should ask in the first meeting with the product development team. If you forget this, you have forgotten everything. They'll know the answer. If they don't, they have one heck of a serious marketing problem.
5. Have I written an adequately detailed outline for the manual?
Actually, you can't know this until you have begun writing in earnest. No doubt you've heard of the outline being a skeleton upon which you hang the organs, muscles, tendons, and flesh (but no fat!). Another way to look at it is as a detailed map that guides you from one point to the next. As you write the outline, you get a solid sense of direction. Without it you can get lost in a hurry.
Personally, I have despised outlines since the 7th grade. I mastered the roman numerals, but had trouble coming up with the topics for the As, Bs, and Cs. Nonetheless, a lot wiser now, I make outlines religiously because without them you tend to write the way some people walk in Shibuya on a Saturday night. For instance, to plot out this two-part series I first created the checklist, which took several hours. The list is now serving as a sort of barebones outline. Filling in the details takes relatively little time. That's the critical role the outline serves, to organize your thoughts and give your writing coherency.
Another reason for the outline: I usually supply the outline to the product documentation manager to make sure he agrees with the basic contents of the manual and their order.
Obviously, it's a lot easier to move a few lines around in an outline than to have to do it much later to large blocks of information. It also may prevent the agony of seeing hours or days of work scratched out because you included information the documentation manager later decided was not necessary.
Finally, the outline gives you a much better idea how much time and effort will be required. The more detailed the outline, the closer to the mark you will be in your estimates of page count and how long the writing will take. Usually, you face both a page limit and a time limit. Your outline can help you come up with a "budget" for both.
During:
Ask yourself these questions as the writing proceeds.
1. Am I keeping to the outline?
The outline helps you get started, then it helps you continue along the original path - but only if you consult it regularly. Sometimes you'll find it to be incomplete or needs more detail. At those times you may need to temporarily stop writing and invest some more time improving your outline. Filling in missing detail isn't so necessary, since that's what you do as you write. How much detail you need depends on your own writing requirements and the complexity of the manual. The important thing, though, is that you follow the general path of the outline, and use it to pace yourself as you write.
2. Am I keeping to the schedule?
Rarely is a technical writer given the luxury of setting his or her own schedule for writing. Instead, the writing deadline is determined by working back from the date of publication, which is usually set according to marketing and production considerations. Your own needs (like sleep and a smile from your kid) is way down on the priority list.
Let me make a momentary diversion. I have the results of a poll taken of U.S. companies about five years ago. The managers of these companies' technical publication departments were asked to estimate how much time and money were spent on a typical 100-page manual. The results were quite interesting.
The average number of writing hours - mind you, only writing - was five hundred. That's a little over three months of eight-hour days, five days a week. The total number of hours spent by the writer, including researching, planning, and revising, came to 640 hours. If you assume only one writer, that means a typical investment of four months in each 100 pages. In just the writing. In Japan, four weeks (albeit, of 10-to 12-hours days, six days a week) seems to be more the industry norm, if you'll let my own personal experience and the comments of others take the place of a creditable poll. Which loops me back to the outline. With such a typically short writing period aboard the technical writing shinkansen that is Japan, it is essential that you budget your time as closely as possible. You can do this by setting time limits (as well as page limits) to the writing done on each section of your outline. Obviously, these time limits can be adjusted as you go along. The idea is to give you a "kilometer marker" that lets you know how far you've come and how far you've still got to go. It also can significantly speed up your writing because you don't have to constantly figure out what to say next.
3. Do I have questions or uncertainty about what I have written?
Here's where the telephone number of your product expert should be used, and used well. Many writers, probably most, type in their questions as part of the text. If they can, they continue writing and bring up the questionable items later. This is the best way to handle it. However, if you discover a major block in your understanding, get on the phone and solve the problem right then. The last thing you want to do is guess about the operation of the product and then later 1) forget to have it verified, or 2) find yourself having to rewrite large sections of incorrect information. E-mailing or faxing your questions can be an even better way of conducting this quick research.
Warning: You take a big risk when you add your own comments to the text. Make sure you have some way of separating your personal statements and questions from the parts intended for publication. I can remember seeing a few ludicrous instances in which a writer's or editor's comments were missed and the product user was subsequently told that "This should be moved to the back of chapter 3" or something of a similar nature. The possibility of this happening in Japan is even greater since the typesetting is often done by non-English readers.
You can limit the risk by making your comments distinct from the rest of the text. One way is to outline, color or enlarge the typeface. I often do that AND add brackets [[[ ]]] around my comments, which makes them easier to hunt using the program's "find" feature. Consequently, my personal thoughts blaze out like a neon sign. So far (knock on wood) I haven't seen one of my "What the hell does this mean!?" in one of my finished manuals.
Actually, one other suggestion about writer comments and questions: Don't make the situation even worse by expressing such un-helpful observations as the one above or "This doesn't make sense!! or even "??????." Take a little longer and ask specific questions to which someone, either an editor or engineer, can later respond. Help them and yourself by including the page number for the specifications or a previous manual where the confusion exists. Being more specific makes it easier to later determine the reason for the confusion.
After:
Ask yourself these questions after you finish writing.
1. Have I written too much? Not enough?
2. Is every sentence as clear as I can possible make it?
3. Would it be better to express some information as a table or diagram instead of text?
Conversely, would these tables or diagrams be more understandable if they were converted into a text description?
4. If I were to use this machine would I consider the manual a help or a hindrance?
5. Is there any way to reorganize it or otherwise modify it to improve its usefulness?
In the final part of this two-part series, we'll attempt to answer these questions and then turn to others the writer ought to consider that involve designing, organizing, laying out, and managing your manual masterpiece.