I'm a technical writer, and here's my perspective.

It is a thankless job. Your name is not included in the end work. The engineers change the specifications and neglect to inform you. There are a minimum of two design spec changes that come to light only after you have sent your manual off to the printer. Kurt Vonnegut, Jr., was correct in stating that Tech Writers must avoid interjecting their opinions or thoughts into their writing. Most tech manuals are bland, boring factual papers.

Why do I write technical manuals? I enjoy it very much. It takes skill to take a product and teach someone how to use it or repair it. I don't write software manuals personally, since I am a hardware specialist. My tech manual writing jobs included training courses for classrooms, component-level repair of hardware, module replacement, and how to use the device. The end audience must be considered in writing technical manuals. Users are the least technical people in general, where component-level repair techs are the most familiar with the inner details of a device.

One outlet for prose is Everything2. I get to voice my ideas and opinions in my writing, so I "get it out of my system" before going back to tech writing.

I love being a technical writer. There's nothing I like better than creating the perfect document. Step after step of "Dispense such-and-such..." or "Sonicate at....". There's something innately beautiful about one's protocols or SOPs locking together to form a crystalline flower of logic. And there's nothing like having a dreaded federal auditor from some nefarious government organ like the FDA come on down, read them, and say, "All right. All cut-and-dried here. No findings on this one."

I would disagree with Kurt Vonnegut Jr.'s opinion that the technical writer eliminates all vestiges of his or her personality from their work. I would say that people do put their personalities into it, no matter how they may try to avoid it. A Heisenberg Principle of writing, so to speak. At least in my field, most of us are extreme anal retentives. We love our little formulae, and have leeway, as long as the imperative: "Write it so some reasonably educated guy off the street can understand it" is satisfied. People have different ways of achieving this while satisfying the documentary templates that we must fill out. Arguments occur all the time, mainly about whether or not one should say something one way or some other way, or semantic minutia. Usually in such circumstances, the alpha technical writer (usually either the higher ranking or better writer) will win, revising someone's document before submission, the literary equivalent of a brutal maiming. Fortunately, I usually win such debacles.

How to Markup a draft document

'Markup' in this context is the process by which an SME (subject matter expert) marks corrections and changes to the text I have written that explains something the SME told me, to a reader who is not expert in the particular subject.

Here are some tips for making markups that fellow technical writers and editors might like to pass on to their SMEs. After encountering yet another example of markup best practice, I felt compelled to record its qualities for the benefit of the industry. It is also a form of stress-relief therapy for me.

Materials needed

A photocopy of the document. This should be at least a third generation copy. If it is too legible, make another copy and be sure to:

  1. leave the photocopier lid OPEN, and
  2. place the original on the glass at an angle of about 30°. It is always useful to shuffle the pages before you staple them seven times.

A biro. This should either be a leaker, or one that is empty, no other type is acceptable. A good source might be your grandfather's desk drawer, or the back of the second drawer in the kitchen cupboard. An acceptable substitute would be a 24H pencil, or a very thick highlighter. Great success has been obtained with whiteboard markers, they give excellent print-through sometimes up to 3 pages deep.

Procedure

  1. Before you start, practice writing very quickly. Increase this speed and maintain it when making your markups. Use ONLY cursive handwriting, and try to make the letters "r", "m", "h" and "n" indistinguishable one from the others.
  2. Write as much as possible in the margins and between paragraphs. On no account should you use an extra sheet of paper for your comments, it is far too much work. Electronic or online markup is far too hard to learn, so ignore it.
  3. Personal abbreviations are very desirable, let your creativity run wild and use a different abbreviation for every occurrence of the same term.
  4. Make sure you make as many changes as possible to every table and diagram, even if they are not necessary.
  5. Always remember, ambiguity is
  6. Tell the project manager that everything is on track, you have reviewed the document and given your comments to the technical writer, then go on vacation. You must not speak to the technical writer before leaving, just put the markup on his or her desk.

The test of whether the markup is of a high standard is whether the SME can read his or her comments, after returning from vacation. The markup quality grade is equivalent to the percentage of comments that the SME was not able to read.

If you are working in a multi-lingual environment, there is another useful technique that can be used. Let's put it between points 2 and 3 above, and call it point 8. Always provide comments in a language other than your native language. The technical writer will be thrilled with the hours of amusement you provide while he or she tries to understand what you are saying by translating back into your language, and hunting for similar expressions you have used in other contexts, to get their meaning.

Log in or registerto write something here or to contact authors.