Quick Editing Guide for Technical Writer

Documentation is like sex; when it’s good, it’s very, very good, and when it’s bad, it’s better than nothing. – Dick Brandon

Technical documents such as User Guide, Configuration Guide, Installation Manual and others must be written in such a way that these translate the complex and puzzling into something that everyone and anyone can understand. When the user reads the user guide, it must obviously guide him and should not confuse him. The step-by-step guide must be clearly stated and logically arranged.

Careless writing will result to spelling, grammatical, and punctuation errors, leaps of logic, ambiguities, missing words, and incorrect vocabulary. These “common” mistakes confuse the readers thus, defeat the purpose of technical documents.

Although it is better to have someone review your work, you can avoid some problems by taking another time checking your document before sending or uploading it. Here are some tips to guide you.

  • Perform a spell-check on the document
  • Search the document for usage errors
  • Search the document for broken links
  • Perform another spell-check

Check the spelling

Read your document between lines. Read it carefully as if it is the first time you read it. Take extra attention on teh spelling of some commmon words. Have you noticed the errors in the preceding sentence? Yes, but some user guides still contain such errors. As technical writer, your responsibility is to deliver well-polished document.

Usage Errors

This is very important. Try to search for is, are, were, by, etc. Read the sentence carefully. Do you need to replace passive voice with the active voice? Check also your tense. A newbie technical writer may write, “Press the start button. The system will …” In this case, “will” should be removed. It must be present tense.

Example:
Avoid: When you press the ENTER key, a warning message will appear on the screen.
Write: When you press the ENTER key, a warning message appears on the screen.

Note: Use SMALL CAPITALS for key names.

Another is the use of contractions like n’t and ‘ve). Replace them with full words. Instead of, “can’t” write “cannot”.

Check bulleted lists and ensure that the first word of each list item is of the same type. Begin each item in a bulleted list with a word of the same grammatical type. If the first item in a list begins with a verb, for example, then all the items in the list must begin with a verb.

Once again, remember that you write to help the readers.

Finally, read through the entire document while imagining that you are an inexperienced user; rewrite anything that could be misunderstood.

As Frederick Brooks advises, present to inform, not to impress; if you inform, you will impress.

______________________________________________
Jerry G. Gervacio|Mandaue City|Contact: Send Mail
Blog I author (Bisaya): Ambot Lang!
______________________________________________

Advertisements

2 thoughts on “Quick Editing Guide for Technical Writer

  1. “When the user reads the user guide, it must obviously guide him and should not confuse him.” – it will become a confusion guide otherwise hahahahha..

    i think i have to tender my resignation and fly back to cebu, submit my application to you and please don’t let me undergo with another panel interview.. just let me sign a contract immediately with a signing bonus….. hahahahaha

  2. humblesoul SME’s (subject matter expert) who writes well produces excellent technical documents..

    ..and you don’t need to visit the kingdom of developers just to ask an explanation what ABEND means.. LOL

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s