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.
