![[Technical Writing Overview]](writlogo.gif)
Technical writing is not creative writing, so forget the cute stuff and deathless prose. Such would not be appreciated. Instead, technical writing is more like textbook writing, except you are required to explain a method, product or process in such a manner that end users might understand how to perform an operation, expedite a process or use a product or piece of equipment. Use the simplest, most straightforward language and descriptions you possibly can, using a minimum of words. Make your words count. Also, avoid jargon and buzz words, unless you are sure that everyone who will read your manual will understand them. Even then, if used at all, it is best to define such words the first time they appear. The same holds true for Acronyms which are a set of initials, usually the first letter in each word of a name. Factuality and Clarity are of utmost importance, and there is little room for imagination. Most technical writing will be in manual form, consisting of several sections or chapters, progressing from the beginning of an operation to the end in linear fashion. The finished product should be readable, clear, concise and understandable.
Technical writing must be done in a clear, concise, non-sexist language and manner that is readable and understandable by the persons who must read it. Obviously, if you are writing a training manual intended for building maintenance personnel, you would write it quite differently than you would a manual dealing with shutting down a nuclear reactor. However, there are all kinds of people of various skill and comprehension levels, and writing a manual above their comprehension level is a waste of time. They couldn't read it. However, seldom do people of a higher comprehension level complain when a manual is well written in an easily understandable manner.
For example, handouts from many state agencies such as social services agencies will be written in sixth grade level language as are most newspapers. Conversely, the "New Yorker" magazine is written mostly in eighth grade level language which is suitable for most technical work. One good way to gauge language level is to visit a public library and spend some time in the youth section. There, you will find books written for most grade levels. You'd be surprised at the vocabulary in fifth grade level books. Just collect a book or two from the sixth, eighth, tenth, and twelfth grade levels and read a bit of each to familiarize yourself with the vocabulary, grammar, and usage, paying attention to the sentence structure and thought patterns.
Another good idea is to buy copies of such books for your reference shelf. That way, before writing a document, you can read a bit from the correct grade level book to get into the "swing" of the writing. Also, MS Word and other modern word processors which include a grammar checker will likely also include a statistics summary that will give you an idea of the level and the readability of any article. This section is written at grade level 9.2 with a readability of 68 which is about right. A readability level of 100 would reveal that you were writing for morons. I suppose that style of writing is valid, but such writing really slows the reader down. Anyway, use good sense when writing any article, but pay close attention when writing technical material, as should your readers fail to comprehend your instructions, trouble would surely be in the brew. Usually, I talk to several examples of the personnel who will be reading the manual, so I can get some idea of their competency level before I start writing a piece. Usually, I can do that while researching the subject material, so no time is lost.
To write a cogent technical article, writers must be familiar with what they are writing about. Guesswork just won't do. That means doing some research, interviewing people and even gaining some hands-on experience or a first-hand viewing and good explanation of the process or product from a qualified technician. When and where possible, get in there and get your hands dirty. Try to see what is going on and try to understand it. If you don't, how can you expect to explain it to someone else? If nothing else, try to understand the theory behind whatever it is you are addressing. The better you understand the product or process you are writing about, the more understandable will be your documentation. Technical manuals are written to train, advise and impart necessary information. Fail on any of these counts, and the piece is worthless.
On a large project, don't try to comprehend it all at once, attempting to learn in a short time what others have spent years assimilating. Instead, try to gain an overview of the product or operation from those in the know. Cultivate these people, gain their confidence, and let them guide you through it. "Divide and conquer!" Break the process up in to manageable sections or modules and then tackle each one separately. Remember get an overview first, so you understand the beginning, middle and end result.
"In this plant, we make boxes. We start with these sheets of cardboard, cut them to size, and then run them through our offset printing press to apply the required labeling and registration marks. Then, they travel down this conveyor belt to the die stamping machine where they are creased for easy folding. Next, they are flat-folded and the edges taped together with brown, reinforced, paper packing tape. The handler then stacks them. After that, they travel by conveyor belt through that binding machine, twenty-five at a time. It ties them and then offloads the bundles onto palates, ready to be loaded onto our fleet of trucks for delivery. The whole process is automated. What we need is a set of training manuals that will teach our employees how to setup, maintain, adjust, and operate the various components of the system."
*Already, you should be able to see that the die cutting and creasing could be done in one operation, so make note of that for later use. Such a change could be worth considerable savings to your employer over the years. Not only would your suggestion lower costs, save time and increase production, but it would obviate the replacement cost of one machine and eliminate one conveyor belt system.
After you have firmly grasped the overview, you will want to break the system into related sections and learn the specifics of their care and operation. You are traveling from the general to the specific. You may then outline each module separately.
All right! Once you have a basic understanding of the product or procedure, lay out a rough, but organized draft as best you can. There will probably be a lot of missing information in your piece, but that is why you are writing your rough draft. The object is not to prove what you know, but what you don't know. Next, get back out there and fill in the holes. Read up on what you can, and ask questions about what you can't find out otherwise. Right! Fill in the holes until you know in your heart that you have everything you need to do a top grade job.
Now, working from your rough draft, you can refine your finished product. Remember, every process has a beginning, a middle and an end. Learn to think in this linear manner. A manufacturing process starts with raw material or a preformed or machined piece, upon which further operations are to be performed. Begin at the beginning and work your way through each operation or process so that any personnel attempting to learn may easily comprehend what you are trying to teach them.
Let's assume the process involves a machine or series of machines. In such case, address first the setup of each machine or component in the process. Is there a start-up procedure? Does it involve a sequence of events? What about preheating or adjustments or measurements? What about end play and run out? How about the conveyance method between processes? Is there a check list? What about safety? What precautions are necessary to keep the operators breathing? Is there an inherent danger to be avoided? A wedding ring caught in a stamper, press, conveyor belt, pulley or gear, can cost someone a finger or worse. Don't even think about getting a necktie caught.
Somewhere in the progression, the material or part to be processed must be made ready. Oddly, this is called "Make Ready." How is the material fed into the machine? Is any preparation necessary? What about temperature? If you are injecting or extruding a liquid material from a container into some sort of mold, at what temperature must the material be maintained to facilitate the operation? To cast lead type or monotype, a temperature of around 540 degrees F will likely be used. More than that, the mold must be preheated to near that temperature in order to produce a smooth casting. What about moisture? How about separation? If you have a stack of paper to be fed into a printing press, you may have to fan the leading edges of the stock to allow a fine film of air between the sheets to facilitate continuous feeding. Should you be stamping or forming a product out of a thick paper, you might need to maintain a constant moisture content. How does humidity affect the operation and feeding of the equipment? Should a humidifier with an automatic sensor be used? What about automatic oilers? To seat a steel piston sleeve into an air-cooled, aluminum engine block, the block must first be cooled with liquid nitrogen to shrink the aluminum away from the bore so the sleeve may be inserted. A technical writer must consider all stations of the process to be dealt with.
Most machinery must be maintained, lubricated and adjusted. To perform these operations, certain tools must be used, so appropriate sections of your working documentation must include such tools, their usage, and the methods of use necessary to bring the machine within working tolerances. If micrometers are needed, the measurements or gaps must be indicated along with instructions on how to read a micrometer. If shims are needed, it would be well to provide a table showing the range of such devices. Often, endplay or run out must be adjusted, so specifications or methodology must also be included to achieve successful operation. Of course, if there is a separate maintenance crew, then this information would be included in their documentation. However, an operator should be able to recognize when the machine or system needs attention so it doesn't malfunction or eject unusable product.
Your documentation should include methodology and guides for spot checking the system output and the specifications for the finished product. A day's run of unusable product would result in quite a loss. There is no excuse for such a loss, and the cost of quality control is miniscule compared to such a catastrophe. Murphy's law hasn't changed much over the years. "If anything can go wrong, it will." Make sure anything that could go wrong is not left unattended or unnoticed.
What happens if something goes wrong? Did a belt jam? Did material get caught somewhere in one of the system modules? Did an adjustment work loose or, did a system failure occur? Ask questions about problems and their fixes. Spotlight troublesome areas and system parts prone to failure. Ask about replacement parts and alternatives. Often a nonproprietary replacement part can be obtained from a third party supplier at a greatly reduced price. This is especially true for pumps and electric motors, as seldom do manufacturers go to the bother and expense of making such readily available accessories. Collect a list of symptoms and fixes from an "old timer" and include them in your manual.
It is difficult to explain tweaking, as this involves hair fine adjustment to the system that would allow for atmospheric changes, static charges, material, temperature fluctuations and or idiosyncrasies or variances due to surface wear or minor damage to feed or transport surfaces. Tweaking is akin to adjusting a carburetor or distributor advance on an automobile for optimum efficiency. Tweaking is also necessary to fine adjust the fountain solution on an offset printing press. Tweaking is learned by experience, trial and error. Therein lies the value of trained personnel. It would be possible, however, to allude to the controls that would make such adjustments possible.
*Seeing as how you are investing time to learn the product or process, and your employer is paying you for that time, try to look beyond the surface, and if you can, figure out a better way to achieve the final outcome or remove a dog leg in the process. Should you find such a condition, mention it or turn in a preliminary report to your management contact. Often technicians do the same job year after year, never seeing an obvious possibility for improvement. Sometimes, a fresh set of eyes can spot a problem area that can be removed, rerouted or rectified. Often, such information can result in a worthwhile increase in production and profitability while lessening downtime or equipment failure.
"A picture is worth a thousand words," say the Chinese, so the inclusion of a few photographs of strategic operations might well be worth their weight in gold in aiding comprehension. This is particularly true in revealing the intricacies of adjustment and feeding procedures. Few operations can be more confusing than the installation of serpentine belts which twine around a series of pulleys, so a good photograph of a correctly installed belt system can be invaluable.
Once you've done your homework, understand your project fully and have a good, complete rough draft, containing all the necessary information, check its hierarchy to make sure each section is in place and flowing in a linear fashion from beginning to end. This document should be made up of several sections, so begin refining each section separately to streamline the thought process and language at whatever level it is written. Cull any unnecessary words, restructure awkward sentences and proofread for mechanical errors and content. Remember, the object is to present the end user with understandable documentation. Assume the end user has no experience what-so-ever, which will probably be the case, so conveying the information in a reliable and understandable manner from beginning to end is all important.
When you have finished your final draft, try to have experienced personnel read and evaluate it. Make corrections, and then present it to your management contact so further input and suggestion might be implemented. Once the documentation is in its highest state, have management OK and then sign off the project that it is to their satisfaction. Turn in the masters, and that's it. You have completed your project in a workmanlike manner.
![[Contact Information]](contact.gif)