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.