Vinish Garg

Technical Writer. Published Author. http://www.vhite.com

Technical Writing: Raise the Bar

leave a comment »

The first few months at first job as technical writer are confusing since you are not always sure what exactly you are supposed to do. Your role is less significant in the company; not all information regarding the project is communicated to you, and you rarely sit late nights or miss your lunch.
It is only after about a few months of experience, when you have developed at least a couple of documents that you begin to understand the finer points of technical writing. Once you know your job, and are comfortable doing it, it gets extremely important to raise the bar.
This is the time when you should learn the difference between a poor document, an acceptable document and a good document, and make required improvements.
Have a look at an example of poor documentation.
Raise the bar...

Raise the bar...

This is an example of poor documentation because of following reasons.
Rectangles in Red color: The space between image and text is inconsistent. It looks as if the image is centrally aligned in a specific area for all three points. One, a centrally aligned image does not look good since the paragraph starts at different positions wrt left alignment. Two, it leaves the space between image and text as unequal.
Circles in Green color: The points in list terminate inconsistently. One of the points does not end with a full stop, while others do.
Circle in Blue color: There is double space between the two words. A technical writer should take not more than 20 seconds to point out if there is a double space anywhere in one page of a document.
Circle in Yellow color: The word the is used unnecessarily, at many places. Though the use of the is very tempting, it is generally not required most of the times.
Circle in Brown color: A technical writer must avoid the continuous form of verb such as clicking. A user control such as a button does not allow a user to do something. Use enables rather than allows. Use words that are devoid of feelings. For example, use required, and not desired.
Advertisements

Written by Vinish Garg

July 5, 2008 at 2:25 pm

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

%d bloggers like this: