(how-to) by zutalors Sat Sep 19 2009 at 15:29:12

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.

I like it!