Memoir of a Tech Writer: The Art of Leverage

by ellG147

When you're a freelance tech writer, projects come in all shapes and sizes.  You never know what the next challenge will be, but you can count on the likelihood of dealing with language and cultural issues since more U.S. tech companies are outsourcing or partnering with companies overseas.

When I was asked to edit a post-translated software manual originating from Europe, I realized I was going to have to do some planning and preparing, especially since I would be working with people whom I didn't know.  So I conducted an informal analysis of the people I would more than likely be collaborating with learning about their preference(s) of communication, daily and vacation schedules, depth of knowledge about the project, and so forth.

And since I was the new kid on the block, I realized it wouldn't hurt to apply some simple psychology (social scaffolding), so I placed a candy bowl and jar of interesting rocks on my desk to develop an instant rapport with coworkers.  Additionally, I let people know that I took the liberty of putting together a photo stock (testing out the company's digital camera equipment) that could be used for recruitment fliers or slide show presentations or other.  You'd be surprised how many people took me up on the offer.  People are always in need of new photos from a fresh perspective because it makes them look good.

In regards to companies, I've found throughout the years that there is usually a very small percentage of people who are willing to help you by being forthcoming with information, guidance, and resources.  Conversely, there are those who help but it is like pulling teeth, or those who will give you just a smidgen of their time because you're on the meter.  In regards to departments, they can be very protective of information and may or may not share information with other departments.

Once I had a general idea of my people resources, I asked myself this important question: Was this manual/software someone's pet project?  If so, whose?  This is an important thing to find out if you can so that you can immediately align yourself with this person or persons.  Ask the individual(s) whose pet project this might be for their help and assistance whenever needed - and for as much insight as possible.  Knowing whether a product will be used primarily as a research tool can make a huge difference in the way a manual is slanted.

Don't hesitate to CC your Pet Project Person(s) (PPP) should things bottleneck or you discover a weak link in your people pool so that you can keep steady, forward progress with your project as some people tend to procrastinate or have other issues.  If your PPPs are up there in the chain of command, this gives you additional leverage.  Use it, but don't abuse it.

A critical decision that needed to be made was how deep to go with the edits of the manual.  Since this particular project involved sociopolitical considerations, things could get rather sticky.  The company who hired me did not want to step on the toes of the developers who wrote the manual, as this might jeopardize work relationships.  However, the manual needed to be improved upon and brought up to the standards of the company who hired me.  So what does one do in a Catch-22 situation?  Work in a gradual rapport with all parties concerned and exercise tact.  Let people know your intent and reasons for doing what you're doing so that there's no room for misunderstanding.  Use phrasing like "...requires some fine-tuning" as opposed to "...requires a a major overhaul."

Since we live in a make-work universe, debating whether to start the manual from scratch or fix the existing manual would both have their challenges.  I chose to work with the existing manual mostly because the developers had already deposited a great deal of energy into the project.  In this case, my choice was based upon a matter of respect.

After reading the first few pages of the manual, I experienced what I call psychological entropy: difficulty in getting through just a few pages without developing a headache due to transposition of words, translation issues, run on sentences, misplaced or lack of articles, improper gerunds, odd word usage, and so forth.  Since getting through the manual was extremely difficult, I decided on a different tack with the goal of making the manual more readable so that more critical editing could take place later.

My first step was to find out if anyone in sales or marketing had already slogged through the manual - in its current condition - as a foundation for developing training or preliminary marketing materials.  If so, perhaps various incarnations of a GOTO reference was already available albeit in the form of rough notes stapled together or text files or other.  If not, then I could at least query these individuals to garner insight.

My second step was to gather background info on the developers by talking to key individuals in the company who actually met them at various company meetings and so forth.  Based on the developers' personality types (in this case socializers), I looked for probable areas of strength and weaknesses in the manual.  Fortunately, I had worked with socializer types in the aviation industry and this provided me with an a priori reason for coming up with probable scenarios in relation to software.

After steps one and two, I proceeded by spot checking the manual while working with the accompanying software, taking down copious amounts of notes, page numbers, etc.  I found enough concrete evidence to support the personality-type theory and this made it possible to roughly gauge how long it would take to fix various areas in the manual along with their co-dependencies.  Ultimately, I was able to come up with a viable work plan (as enumerated below) that would help me accomplish the goal of making the manual more readable.

Work Plan

0.)  Review images and charts and tables.  Fix any glaring errors in the tables, charts, images.  Get updated visuals if needed.  Send request promptly to the necessary parties.

1.)  Take care of the technical material: check with resource engineers about part numbers, system offerings, transformers, proper cables, EMF issues.  Revise chapters and paragraphs and captions and images.

2.)  Review chapter on installing the software and troubleshooting.  Consult the software engineer in sales or support or other.

3.)  Remove all marketing content/braggadocio.  Use FIND and REPLACE menu options to expedite cleanup of misplaced words and missing articles, improper gerunds, contractions, etc.

4.)  Embellish where lacking (click tabs in software to see what you get and see if this is written up in the manual).  Also, are these screens included in the manual - and should they be?  Or should they just be written up in paragraph form?

5.)  Carefully review chapter on modes of operation of the software.  Is it clear and correct and does it contain a logical flow?  Spend a good deal of time on this core chapter and use it as a paradigm for the rest of the manual.  All pertinent information should be grouped into paragraphs and not scattered about.

6.)  Review the safety instructions.  Make sure they are correct and complete and repeated in areas where needed because of liability issues.  Have resource engineer review this section as well to be sure material complies with U.S. standards and laws.

7.)  Add more images where it would help to clarify the text.  Set up photo session at the end of each work week during early morning hours.  Use internal resources as subjects.

8.)  Get a perspective: print out various pages or chapters and have others review it and provide feedback based on a questionnaire that will be provided.  Rework areas based on feedback.  Keep all questionnaires and use as testimonials (if needed).

9.)  Convert manual to plain text and specified font type.

10.)  Have QA and select others in the company to review and critique the manual once again.  Print and bind.  Provide questionnaire.

After each milestone, I sent email updates to targeted individuals to let them know the status of the project as well as to demonstrate progress and to elicit early feedback.

Once the manual became more readable, it made it easier to determine what needed to be done to bring the manual up to company standards.

At this stage of the game, I never hesitated to ask myself what I needed to do to work harder at bringing to fruition my secondary, tertiary, and quaternary goals for the project.

Finally, when the manual was near completion, the people who were extremely helpful with the project received positive feedback and a note of gratitude.  Their supervisors also got wind of their cooperative demeanor.