Tuesday, December 16, 2003

Letter to an Indian tech writer

I wrote the following letter to a technical writer who has a column at http://www.expressitpeople.com.

Subject: Great columns on technical writing
Date: Tue, 16 Dec 2003 20:19:48 -0800
To: documentor@vsnl.com

Hello Gurudutt,

I am a Sun Microsystems technical writer whose job is probably going off-shore to India. In searching the web for anything to support my theory that one cannot automatically assume that Indian English is the same as American English, I found two of your columns, "Grammar stammer" and " the art of stylish writing." You're good! You write very well and make good points.

When you wrote that simplicity and brevity are essential with tech writing, I agree wholeheartedly. But I want to quibble with one idea, where you wrote that if a writer creates a manual, the goal should be that "the users of the system should accept the system wholeheartedly."

By the time users are reading the manual they must have accepted the system. At that point they need to know how to use it.

I have always held that technical writers have to get out of the way of the readers. Find out what your readers need to know, tell them, and stop. Use as many words as you need, but no more.

In any kind of writing, as you are aware, the goal is not to get the reader to pay attention to your writing. Samuel Johnson wrote that if you write something that strikes you as particularly clever, you should strike it out!

Keep up the good work.

My son is going to Chennai to train CISCO tech writers in January, and I might go along with him to write an article about off-shoring. So I might be in your country sometime soon for the first time.

Enough about me!

Regards,
Post a Comment