I have written technical materials most of my life. The past few years are the first time I have written just for the pleasure of it. In previous years as the head sales guru for custom built robotic and factory automation companies, I was always in charge of the proposal generation. There's an old rule of thumb in the aerospace business that the weight of a proposal should be one pound per million dollars bid. There was a lot of truth to this.
I really had two tasks. The first was to edit the technical stuff that came out of engineering for readability (spelled Americanized English). I'm a techie guy, and if I didn't understand what was being said, the reader most likely wouldn't either. In that same category, all of the wafflings had to go away. Either you can do it, or you can't. And none of this "we think we can, or believe it will work" stuff. It doesn't engender confidence in the proposal. Cleaning this part up also generated some animated meetings with engineering staff.
I really had two tasks. The first was to edit the technical stuff that came out of engineering for readability (spelled Americanized English). I'm a techie guy, and if I didn't understand what was being said, the reader most likely wouldn't either. In that same category, all of the wafflings had to go away. Either you can do it, or you can't. And none of this "we think we can, or believe it will work" stuff. It doesn't engender confidence in the proposal. Cleaning this part up also generated some animated meetings with engineering staff.
My second task was to personally write the executive summary. This was about five to seven pages depending on the complexity of the quotation. This audience really only wanted to be assured that it will work, stay in budget, and deliver on time. Tech talk was held to the bare minimum, and the benefits of choosing our proposal were emphasized. Words like experienced, skilled, successful and so on were sprinkled onto a bed of confidence.
I don't write this stuff anymore, but the nature of my work requires me to plow through voluminous quantities of technical documentation, and I'm not very impressed with a lot of what I see. We will now embark on a review of current technical writing forms.
"Height of Brevity." We have all seen it. Instructions like, "Locate the appropriate device driver online, download and install it." Or, "Interface the chart plotter to the NMEA serial to USB converter." This is typically written by people who assume like them, you are an expert at this also, and will intuitively know how to do this. This is the stuff that makes you tear your hair out. What Driver? Download from where? How do you install it? Worse, if you need some help, it is often only available by email with responses like, "You didn't do it right, try again."
"Footnoter" This type of writing requires all critical connections, and setup information to be printed at the bottom of pages like a footnote in type so small you need a magnifying to read the text. They take a form like, "Failure to connect the green wire to the blue wire prior to applying power will result in your equipment spontaneously combusting, and will thus void your warranty.
I don't write this stuff anymore, but the nature of my work requires me to plow through voluminous quantities of technical documentation, and I'm not very impressed with a lot of what I see. We will now embark on a review of current technical writing forms.
"Height of Brevity." We have all seen it. Instructions like, "Locate the appropriate device driver online, download and install it." Or, "Interface the chart plotter to the NMEA serial to USB converter." This is typically written by people who assume like them, you are an expert at this also, and will intuitively know how to do this. This is the stuff that makes you tear your hair out. What Driver? Download from where? How do you install it? Worse, if you need some help, it is often only available by email with responses like, "You didn't do it right, try again."
"Footnoter" This type of writing requires all critical connections, and setup information to be printed at the bottom of pages like a footnote in type so small you need a magnifying to read the text. They take a form like, "Failure to connect the green wire to the blue wire prior to applying power will result in your equipment spontaneously combusting, and will thus void your warranty.
"Legalist" the first five pages of a manual starts with things like, "To ensure your safety and relieve us of any and all liability you must wear a gas mask, eye protection, and rubber gloves.
Do not use chains saws, child labor, wood chippers, or hydrochloric acid to install. This product can barely perform its task under normal use and has fragile parts. Do not drop, take apart, open, boil, smash, flush, spindle, drool on, deform, stab with scissors, shred, microwave, bake, run over with your car, incinerate, paint, or insert small mammals into the device. This product may not be safe for persons with peanut allergies, and is not edible.........."
Page 6 says, "Install your LED cockpit light, and connect the red wire to a 12 volt power source, and the black wire to ground."
"Tower of Babel" This comes about when a manual is designed to simultaneously provide instructions in at least twelve languages rendering it virtually useless to all twelve users of those languages. This format is most effective when each paragraph is translated in succession twelve times.
"English as a Fourth Language" First press CAL then unpush OFF key when enter. Please untie ON/OFF key. The LCD show until the inner code is stable, unpress ON. When LCD displays "1", it clues to unpress OFF. The LCD displays "PASS" after displays. Unpress ON, then calibration complete."
"English as a Fourth Language" First press CAL then unpush OFF key when enter. Please untie ON/OFF key. The LCD show until the inner code is stable, unpress ON. When LCD displays "1", it clues to unpress OFF. The LCD displays "PASS" after displays. Unpress ON, then calibration complete."
"Pictographology" This form of technical document uses only pictographs instead of those pesky word things. This is particularly effective for those with a poor grasp of written language. You can see in this example the instructions on how to tune your Sirius stereo receiver to get the all Barry White channel.
"Omiter" This style requires the elimination of important information such as fuse sizes, connections needed, and setup requirements. This is really a collaboration between the Technical Writers International and the Alliance of Technical Support Personnel unions. By omitting information, the technical support staff is guaranteed full employment.
I've had my fun now. I know from personal experience technical writing is a difficult job to do well. In all too many cases the people who do the writing, have never had the opportunity to install or use the gear they write about in real-world conditions. It's the nuances that bite hard. That small but critical piece of minutia whose absence becomes apparent in the middle of a complex install resulting in a delay. A call to tech support, trip to the store, or lots of pejorative language.
Making things worse is the rapid change in technology that leaves documentation always two steps behind and in a bit of disarray. I think that the technical documentation department budgeting in companies is always smaller than it should be, and it's a shame because it's so vital to the users. It's also costly because it puts a larger burden on the technical support departments that have to fill in the gaps.
What's the answer? Go to the installers who have to make it work, and listen to them. I've done this a couple of times for companies. The alternative is to send the tech writers into the field to work with installers, and heck send some product designers along also. I can always use some free help. This would provide some enlightenment, and I have plenty of liquid bandage. It can get better.
The fountain pen photo is from Wikipedia by user Stipula
"Omiter" This style requires the elimination of important information such as fuse sizes, connections needed, and setup requirements. This is really a collaboration between the Technical Writers International and the Alliance of Technical Support Personnel unions. By omitting information, the technical support staff is guaranteed full employment.
I've had my fun now. I know from personal experience technical writing is a difficult job to do well. In all too many cases the people who do the writing, have never had the opportunity to install or use the gear they write about in real-world conditions. It's the nuances that bite hard. That small but critical piece of minutia whose absence becomes apparent in the middle of a complex install resulting in a delay. A call to tech support, trip to the store, or lots of pejorative language.
Making things worse is the rapid change in technology that leaves documentation always two steps behind and in a bit of disarray. I think that the technical documentation department budgeting in companies is always smaller than it should be, and it's a shame because it's so vital to the users. It's also costly because it puts a larger burden on the technical support departments that have to fill in the gaps.
What's the answer? Go to the installers who have to make it work, and listen to them. I've done this a couple of times for companies. The alternative is to send the tech writers into the field to work with installers, and heck send some product designers along also. I can always use some free help. This would provide some enlightenment, and I have plenty of liquid bandage. It can get better.
The fountain pen photo is from Wikipedia by user Stipula
I once had the task to transcribe some service manuals for Watsila Vasa diesel engines from professionally translated Finnish to English. Took me forever to figure out that the translator used 'condom ring' for every instance of 'O-Ring'. :-)
ReplyDelete