Tuesday, November 16, 2010

Evolution: 1983-1990

I worked those seven years at Martin Marietta in Denver. We used Wang word processors. PC's were still more overpriced toys than serious office machines in 1983. The Wang system consisted of terminals connected to a mainframe computer. We had up to five writers cramped in a small room with old government issue desks pushed together. The writers shared one word processing terminal for each room, so we did a lot of writing longhand.

Illustrations were generated from a separate department using AutoCad machines. In those days, the graphic artist sat in what looked a chair used for checkups in an optometrist’s office with lots of mechanical controls within reach in all directions and big screen attached to the front. The room was kept dark and the effect was like sitting in a space capsule. While a simple drawing may not take long, a complex one could take a week or more.

The writers would mock up illustrations to submit to the AutoCad department. We learned before long that the more accurate and detailed the mock-up, the quicker the turnaround and fewer revision required for the finished drawing. This forced us to develop skills designing isometric drawings, callout placement, and designing illustration that would fit on the page economically, making the best use of space to enhance rather than displace text.

Having to put this much work into the drawings made us better writers. We had to pay such close attention to the details of how the mechanisms worked that writing about them came naturally.

Saturday, October 23, 2010

Evolution: Transition 1983

By 1983 I had been at FMC in San Jose three years. In the early 80's if you had been in a job over two years in Silicone Valley, you were considered stagnant. During those years, young workers made a second career of job hopping. I had come to all this from the outside (California) world, and didn't buy into the job hopping but, pushed on by peer pressure, in November I went to a job fair. Several fellow writers from FMC had gone to the fair earlier and were recruited by Martin Marietta in Denver. They convinced me to go to the fair and I agreed to an all expense paid interview in Denver.

I had never been to Colorado. I had envisioned Wyoming as a place to escape the fast pace of Silicone Valley, but Colorado would be close enough. California has a reputation for being laid back, but the truth is there it takes a lot of energy to maintain that image. To me is was more like a buzzing hive, and I was ready to move on.

When I interviewed in Denver, Martin Marietta was hiring droves of writers, editors and logistic support analysts to support the Peacekeeper (MX) missile project. They offered me more money than I made in California and full relocation. I fell in love with Denver at first sight, and signed on. The only hitch was that I had to move to Denver and start work within a couple weeks, December 5 at the latest.

Martin Marietta arranged for a mover, so I packed everything else in my 1978 Datsun pickup and Thanksgiving weekend, to avoid bad weather north, I drove from San Jose to Bakersfield and across the desert to Las Vegas. I spent the night in Vegas then left before dawn traveling I-40 through Flagstaff to Albuquerque. I stayed overnight, then took I-25 to Denver. It was -25 degrees in Denver my first week there.

During the interview process in November, I had a one-on-one with the director of technical publications. He told me that when I came to work for Martin Marietta I would be joining a family and I would be taken care of for the rest of my career. He had been there 35 years, since he came out of college. Two months after I moved to Denver, he was laid off. He was at the end of the last generation where you could confidently believe in a safe job for life at a corporation. My generation watched that generation's beliefs crushed and had to learn to adapt to the new culture. That is evolution.

Thursday, October 14, 2010

Evolution: 1980-1983

I came to technical writing through Kelly Temporary Services in 1980. I was hired as a temporary proofreader at FMC Corporation in San Jose, California. FMC started in 1883 when John Bean invented an innovative insecticide spray pump. In San Jose in the early 1980's we built tracked military vehicles including the LTV-7 landing craft, the M113 armored personnel carrier, and the Bradley Fighting Vehicle, all of which I worked on.

I worked a few months as a proofreader before being taken on as a direct hire as a technical editor. I worked in that position for several more months before moving up to technical writer.

At that time the state of the art equipment for the technical writer was the IBM Selectric typewriter. Typesetting was done by a special department (which I worked in briefly) that manually typed the information into a mainframe word processing program. This turned out to be useful years later when I was learning HTML. In that old program you had to enter carriage returns, tabs, etc. as tags just as in HTML. Later I worked with a state-of-the-art Kodak typesetting system that printed publication-quality pages on photographic paper at an unimaginable cost-per-page.

During that period there were no classes in technical writing, much less college degrees. Companies were looking for journalism majors, which I wasn't. I got in by going through the temping back door, which is still a nice inroad if you don't have the "right" degree.

When I was working at FMC the entire technical writing department, below middle management, was under 30 years old. Anyone older either moved into management or on to another job. In Silicone Valley at that time, if you stayed more than two years at a job you were stagnant. I didn't buy into that environment and moved on to Denver and Martin Marietta in December 1983.

When I left, an Apple II personal computer cost $10,000 and PC's were in the future.

Monday, October 4, 2010

Assumptions

Assumptions are tricky. You have to take into consideration the skill level of the reader performing a task so you don't waste their on things they should already know. You also need to take care not to assume they know acronyms and terminology that is common within the company or industry, but not outside the company.

If you are documenting professional design software, you should be able to assume the reader knows how to open a Windows or Mac program and what a cursor is. You cannot assume they will be able to infer how layers work in Photoshop or how the filters work, unless that training is a prerequisite to your document.

In the early 1990's there was a trend for companies to do away with professional technical writers in favor of engineers or business analysts writing the documentation. The problem with this was those people were too close to their products. Have you ever tried following the user guide for a stereo amplifier that is filled unfamiliar jargon and missing steps?

A procedure needs to describe and illustrate every step that needs to be performed to satisfy the purpose and scope of the task. If the reader is required to remove a part, the steps need to tell them where the part is, how to remove whatever is necessary to allow it to be removed, and how to remove it. If there are any acronyms or unusual terms, define them. You need to mention all mounting hardware that has to be removed and the quantity to prevent the reader from missing any and possibly damaging the part. In other words, you need to make it as difficult as possible to the reader to make a mistake. That doesn't mean you need to tell the reader which direction to turn the screws, but you do need to point out any special tools needed and hazards that may be encountered.

Saturday, October 2, 2010

Consistency

Technical writing is not creative writing. Do not try to find different ways of saying the same thing in the same document. The goal in technical writing is to communicate everything the reader needs to know to perform a task with the least possible opportunity for the reader to misunderstand.

Consistency can seem boring, but if you use the simplest and most clear language possible, all readers should interpret the instructions correctly. Adding unnecessary adjectives, articles, adverbs, and other embellishments just gives the reader opportunities to confuse the matter.

Do not change the name of an item after it has been mentioned once. This should be a no brainer, but I've seen manufacturer manuals where there same part was called by two or even three different names. I've seen manuals where a part was called one thing in text and another in the illustration. The situation is worse when there are several manuals for a piece of equipment that were apparently written by different departments.

The answer to this problem when I was writing military manuals was having a staff of technical editors who ensured all documents were consistent in format and wording and compliant with military specifications. The problem in civilian companies I've found is that the technical publications staff usually consists of a couple writers at most and the editing consists of reviews performed by subject matter experts on the sections that concern them. Seldom does anyone look at the project as a whole. So, it is up to the writers to edit their own work, and no matter how closely they proof they will likely overlook some mistakes they made in the first place.

Sunday, September 26, 2010

Internet Research

When you need to write about vendor-supplied equipment, you may find that the source material provided by your company is outdated or incomplete.  In that case, you will need to dig further to get what you need an accurate procedure.  Twenty years ago that meant searching through microfilm, microfiche, corporate libraries, and writing to or calling manufacturers and then waiting for them to mail what you needed.

The Internet eliminates the need for most of those headaches.  Every once in awhile a situation will arise where no information is available online, usually because the company went out of business years ago, but there is almost always a way to find what you need.

The obvious place to start is the vendor's web site.  Look for a link to something like a "Literature and Document Library" or "Manuals and Drawings" (it may be under "Support" or "Downloads").  You may need to look up the specific product and look for a link on that page. 

Some companies will have an extensive amount of literature on line.  For a company that is a major supplier to an industry, or several industries, it is in their best interest to make this information readily available to their clients to cut down on requests for the manuals, brochures, data sheets, catalogs, and drawings.  John Deere, for instance, has online versions of all their manuals, including complete sets of engineering drawings.  I have occasionally found information on the manufacturer's international sites that is not available on the American site.

Other companies have a great deal of information, but you need to register on the web site to prove you are working for a client before you can get to it.  Permission will be given immediately or in a couple days, depending on the level of verification required.

If you cannot find anything on the manufacturer's site, you can search for the equipment in a using Google or another search engine.  You can sometimes find manuals, drawings, and marketing materials on distributors' sites.  Trade magazines, industry forums, and even other clients may have information on their sites.

As a last resort, if the piece of equipment is used for a very specific purpose, you can search for similar equipment by other manufacturers.  If you collect enough data on competitor's equipment you can deduce that your equipment will have common characteristics that will require the same maintenance.  Then, by examining the equipment itself and consulting subject matter experts, you can produce a procedure that can be further reviewed and verified in the field.

Thursday, September 23, 2010

Creating Line Drawings

I regularly use engineering drawings in my procedures.  However, just copying them in makes for really sloppy results.  This is becuase of the background "noise" in the drawings when copied.  That is, the background is not all white.  It contains hundreds of versions of colors that are almost white.  When these are printed in black and white, you get black specks.

If it is not already electronic, I scan an engineering drawing and save it as a PDF file.  Then I adjust the PDF to the size I need.  I take a screen shot of the PDF and copy it into MS Paint (yes, the free drawing program in all Windows systems).

I outline all outline all of the drawing I need in red.  Then I erase everything that is not red.  That is not as easy as it sounds.  I save the best version I can as a BMP (bitmap) file, then open it in GIMP, a free open source graphic program.  I convert red to black and save the file.

I then open it back in Paint and change everything that is not black into red.  I save the file and open it again in GIMP.  I convert all red to white, and what I have left is a perfect black and white line drawing.

I open the drawing again in Paint and add any callouts or details needed.  Then I save the drawing as a JPG and it is ready to drop into a Word document.

This is a lot of work, but the resulting drawing can be manipulated with overlays and other effects and reused throughout the project.

Wednesday, September 22, 2010

The Process: Writing a Mechanical Procedure

The first step is to define purpose and scope of the task.  This is often obvious.  If the task is to lubricate a pump, the purpose is to lubricate and the scope will be the points that need to be addressed (grease bearings, check oil level, add or change oil). 

If the task is more complex, say an annual inspection of a system, I will do research to define the scope.  This may involve consulting previous work orders, manufacturers' manuals, engineering drawings, and/or consulting engineers or the manufacturer's representative.

The second step is to create an outline or rough draft of the procedure to be sure all points are covered.

Then, if at all possible, I will examine and photograph the equipment.  This is done to aide in illustrating the steps and to identify any obstacles that will need to be addressed.  Recently I was writing about rebuilding a pump.  A special tool was supplied by the manufacturer to aid in removal of the impeller.  The pump was mounted too close to the suction pipe for the special tool to be used.  Providing a solution to this problem made the procedure not only more accurate, but essential to performing the task in the field.

Finally, the procedure is written in final form with steps illustrated to make sure the person performing the task has everything they need to do the job without having to take time to do research themselves.

For an example of a completed mechanical procedure go to www.tomperson.com/downloads/sample_maintenance_procedure.pdf.

Wednesday, September 15, 2010

The Project

The project is the scope and purpose of documentation required for a product, be it software, mechanical, electrical, or any combination of the three.

A software program may require a user manual, administrator guide, help pages, training materials, marketing aides, and presentations.  A mechanical device may require an installation and operation manual, preventive and corrective maintenance procedures, training materials, an illustrated parts list, technical bulletins, and specification sheets.  Electrical documentation may include functional descriptions, hazard analysis reports, user guides, and troubleshooting instructions.

Documentation for a major project like a power plant would include software, mechanical, and electrical elements broken down into systems.  Systems may relate to types of equipment (all conveyors), areas (all equipment related to the boiler), or functions (the flue gas system).

The client will specify elements of the project and the documentation necessary.  They may have existing templates or documentation specifications, but they may ask the technical writer to provide outlines and formats.