How to Improve Your Writing - A Checklist for KB Articles
PSS ID Number: Q107821
Article last modified on 11-09-1994
PSS database name: TECHINFO

1.00 2.00 3.00
WINDOWS

SUMMARY
=======
When writing Microsoft Knowledge Base (KB) articles, strive to make your
writing invisible. Good writing is transparent. When readers notice
your writing, they are distracted from the subject of the KB article, and
you fail to meet your goal to inform the reader.
Apply the following seven tips to make your writing transparent. By
applying these tips, you can add power to your KB articles and help
the reader move quickly to the heart of the information:

 - Use active voice.
 - Use present tense.
 - Be consistent and use parallel constructions.
 - Obey rules of grammar.
 - Use short sentences and short simple words.
 - Use lots of steps and bullet lists.
 - Keep lists to a maximum of seven bullet items.

MORE INFORMATION
================

Active Voice
------------
Active voice tells the reader who did what to whom. A sentence is either in
active voice or passive voice. Passive voice hides the subject (the who) of
the sentence, as in this example:
   The BuyIt application is started.
Active voice makes it clear who is doing what, as in these examples:
   Start the BuyIt application.
   Code in the Command1 button's Click event starts the BuyIt application.
Active voice gives the reader all the details, so the reader doesn't have
to stop and ask, "Should I do that or is that something the application
will do?"
Active voice is not related to tense. This is a common misconception. You
can give a sentence active voice and past tense:
   She wrote the code yesterday.
And you can give a sentence passive voice and present tense:
   The code is being written right now.
To find passive voice, look for variations on the verb to be, such as is or
was. These verbs often indicate passive voice. The verbs is and was are not
action-oriented verbs, so they don't have the power that action verbs and
active voice has.
Readers will have more confidence in the material in the article if you
present the information using powerful language. Readers pick up on the
confidence in your writing. It rubs off on them. You can easily convert
from passive to active voice by rewriting the sentence to add the subject
and eliminate the weak verbs.
Active voice requires that you identify the person, event, or thing that is
taking the action described in your sentence. If it is a person, use the
word "you" to address the reader. This pulls the reader into your article,
and clarifies when he or she is required to do something. It also makes it
easier to read the article over the phone. If the sentence or clause begins
with an action verb, you can eliminate the "you" because it will be obvious
that you are addressing the reader. In all cases, use "you" rather than
"we" to avoid an unintended condescending tone.

Present Tense
-------------
When reading your article, the reader is in the present. The time is now.
By matching the article's tense to the reader's experience, you achieve
another level of transparency. Also, by always using present tense, you
avoid mixing tenses in the article, and you can use fewer words. The
urgency of present tense matches the urgency the reader feels, making your
writing both powerful and invisible.

Consistency & Parallelism
-------------------------
In general, people stop when they notice exceptions. By eliminating the
stopping places in your article, you make it easier for readers to
concentrate on the technical material. For example, if you have a list of
five bullet items -- three that begin with a noun and two that begin with a
verb -- your reader will be more likely to notice that inconsistency than
notice that there are five important items in the list. Where possible,
start each item in a list with a verb, and follow the standard formats for
KB articles.

Conclusion
----------
The best way to improve your writing is to write. Then edit your first
draft, applying the seven tips listed above.

Additional reference words: 1.00 2.00 3.00 dskbguide
KBCategory: kbref
KBSubcategory: RefsPSS

=============================================================================
Copyright Microsoft Corporation 1994.