Welcome to KGS
Downloading and Installing CGoban, the KGS Client
CGoban Main Window
Introduction to KGS
KGS Plus
KGS on Androidâ„¢
Terms of Service
Admin Announcements
Newbie FAQ
Main KGS Window
Set Preferences
Server Stats
"New Game" Window
Game Window
Playing Games
Game Types
Supported Rule Sets
Supported Time Systems
Tagged Games
Rating System
Rating System Math
Main FAQ

Information for Help Editors
Resources for Help Editors
Help Discussion
Recent Changes
Translations Available (click a flag to view):
English (United States)

The Art of Technical Writing

Guidelines for High Quality Technical Writing

John Gayle Aiken IV, PhD

August 25, 2010

1) Eliminate all tenses except for the present tense.

2) Eliminate the subjunctive mood.

3) Eliminate the reflexive voice.

4) Replace prepositional phrases with nominative adjectives whenever possible.

5) Eliminate parentheses as much possible.

6) Find ways to get your point across with fewer words if possible.

7) Avoid TMI (too much information): Shy away from off-topic subjects, and unnecessary information even if it is interesting or useful.

8) Eliminate idiomatic expressions if possible.

9) Use "you" whenever possible.

10) Use parallel constructions.

11) Paint verbal pictures to emphasize your message.

12) Be fastidious about the elimination of ambiguity, even to the point of introducing redundancy if necessary.

13) Verify that your text says what you want it to say.

14) Avoid misunderstandings by saying everything that you need to say.

15) Ensure that the reader does not have to work to understand your message, but, at the same time, avoid being repetitious.

16) Preserve the easy flow typical of stream-of-consciousness, conversational, or narrative text.

17) Replace longer words with shorter, simpler, or more common words if not too much meaning is lost.

18) Replace anglicized Greek and Latin words with core English words.

19) Write for your audience. Do not "talk down" to your audience.

20) Use the grammar, spelling, and style that is normal for high quality writing.

The application of these guidelines in your technical writing is a sophisticated task. There is a dynamic tension within them that requires a creative resolution in many cases. Implementing these guidelines in your own work is an art form.

Good technical writing requires multiple passes through the text. In any context, two passes is the minimum requirement. If you find yourself "improving" a section of text and then putting it back the way it was, it may be time to stop.

These guidelines have been culled from many sources. The selection is based on the author's 40 years of experience with technical writing. In general, these guidelines express, in the context of technical writing, the essence of "The Elements of Style" by Strunk and White.

In addition to "The Elements of Style," two good references for guideline number 20 are "The Secretary's Handbook" and "The American Heritage Dicionary."

Guideline number 10 (regarding parallel constructions) is from the difficult-to-obtain book "Rhetoric" by Edmund Burke. Some university libraries still have a copy of this marvelous little book.

Edit this page (requires admin or translator privilege)