How To Contribute Articles to the Microsoft Knowledge Base

The information in this article applies to:

- Professional and Enterprise Editions of Microsoft Visual Basic,

  16-bit only, for Windows, version 4.0

SUMMARY

This article explains how you can write and contribute Visual Basic articles to the Microsoft Knowledge Base.

MORE INFORMATION

There are at least four different ways you can contribute to the Microsoft Knowledge Base:

• Contribute a fully-tested code sample containing ample comments and a short description.
• Contribute a rough draft of an article that is complete with fully- tested technical information but that needs rewriting, editing, and formatting.
• Contribute a fully-tested, well-written article that needs formatting.
• Contribute a fully-tested, well-written article in the standard format.

Submission Guidelines

When submitting an article, please ensure that it is fully tested and includes all the following information in the body of the article:

• Name of the author(s) or contributor(s).
• Name of the person(s) who signed off on the technical review.
• Product name(s).
• Product version number(s).
• Operating system(s).

Contributions from Microsoft Employees

If your article has been technically reviewed, include the name of the technical reviewer in your article.

If the article is for a product that you support, please submit your article according to your usual Knowledge Base article submission procedures. If the article is for a product you do not support, please email it to the KBINPUT alias. A Knowledge Base Lead will submit your article for you.

Contributions from Outside Microsoft

If you are not a Microsoft employee, you can still contribute. You need to find a Microsoft employee to sponsor you and review your article for technical accuracy.

If you need us to assign a sponsor for you, please send mail to

   ykbfeed@Microsoft.com

In the body of the message, please include your name, the name of the product, a short summary of your article, and your telephone number. We will have a Microsoft sponsor call you to discuss your article. The sponsor will advise you on the appropriateness of your article for the Knowledge Base. If your article is selected for the Knowledge Base, your name will be included in the body of the article as the contributor so that readers can contact you directly if they have questions.

Writing Style

You don't have to be a writer to contribute to the Knowledge Base. The Developer Support Knowledge Base team can rewrite your material for you. All we need is complete, well-tested technical information.

If you would prefer to write your own article, please follow these and the other general guidelines listed in this article:

• Emulate the writing style and standards used in the product manuals and Help menu.
• Use active voice, present tense, short sentences, steps, and bullets to make your writing clear, crisp, and easy to read.
• When writing about bugs, list the symptoms first followed by the cause (if known), and then the workaround or resolution.
• Spell check your article.

Format Style

If you want to put your article in standard format, follow these guidelines. Each article should be organized into sections. There are two basic format styles:

• Informational and how to articles use the Summary...More Information format. For example, this article is in Summary...More Information format.
• Bugs and other problem articles use the Symptoms...Cause...Resolution format. For an example, query on the following words in the Microsoft Knowledge Base:

        visual and basic and kbbuglist
  

Reference Section

Many articles also include a References section at the bottom of the article. When referring to the manuals or products, please use the official names. For example:

• Microsoft Visual Basic Programming System for Windows, version 4.0, Professional Edition, "Professional Features," page 209, "ODBCTimeout and QueryTimeout" section.
• Microsoft Visual Basic Programming System for Windows, version 4.0, "Language Reference," page 145, "Comments Property" section.

Categorization and Reference Keywords

1. Add the following section to the bottom of each article:

   KBCategory: KBSubcategory: Additional reference words:

2. On the bottom line, fill in any reference words that you think may be useful when querying for the article. For example:

      Reference Word    Description
      -------------------------------------------------------------------
   
      buglistx.xx:      Problem in article occurs in version x.xx of the
                        product. Version numbers are carried out to
                        hundredths in the buglistx.xx reference word.
                        For example, buglist4.00 buglist4.00b means that
                        the problem in the article occurs in versions 4.0
                        and 4.0b. Also include kbbuglist on the KBCategory
                        line.
   
      fixlistx.xx:      Problem in article is corrected by version x.xx.
                        For example, buglist4.00 buglist4.00b fixlist4.50
                        means that the problem in the article was corrected
                        by version 4.5. The version number field at the top
                        of the article should not contain "4.50" because the
                        problem is not an issue there; it should contain
                        "4.00 4.00b." Also, include kbfixlist on the
                        KBCategory line.
   
      docerr:           Marks an article concerning an error in the product
                        documentation. We recommend querying on kbdocerr and
                        the product database name, and writing all those
                        changes into your manual. Also, include kbdocerr
                        on the KBCategory line.
   
      softlib           Marks an article that refers to a file contained in
                        the Microsoft Software Library (MSL). Also, include
                        kbfile on the KBCategory line.
   
      appnote:          Marks an application note article that is already
                        prepared on paper and/or disk and can be sent to
                        the customer. Also, include kbappnote on the
                        KBCategory line.
   
   

3. On the top line, fill in the appropriate article subject and type keywords. For a listing of these keywords, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q94671

      TITLE     : Categories and Keywords for All Knowledge Base Articles
   
   

4. On the middle line, fill in the appropriate subcategory keywords. To find the list of available subcategory keywords for a particular product, query on the following words in the Microsoft Knowledge Base:

         kbsubcats or kbkeyword
   

Boilerplates

There are several boilerplates that go on many if not all articles. Put the following at the top of every article to identify the product and version numbers. Modify this boilerplate to give the actual product name:

The information in this article applies to:

• Standard, Professional, and Enterprise Editions of Microsoft Visual Basic, 16-bit and 32-bit, for Windows, version 4.0

or

The information in this article applies to:

• Standard, Professional, and Enterprise Editions of Microsoft Visual Basic, 32-bit only, for Windows, version 4.0

or

The information in this article applies to:

• Professional and Enterprise Editions of Microsoft Visual Basic, 16-bit only, for Windows, version 4.0

If Microsoft has confirmed that the problem described in the article is a bug, please add the following Status section below the Workaround or Resolution section:

   STATUS
   ======

   Microsoft has confirmed this to be a bug in the Microsoft products
   listed at the beginning of this article. We are researching this problem
   and will post new information here in the Microsoft Knowledge Base as it
   becomes available.

Miscellaneous Guidelines

• Always use the complete name of the product. For example, use Visual Basic, not VB. Use Microsoft Access, not Access.
• Use the uppercase and lowercase standards as shown in the manuals. For example, controls such as command button and list box are in lowercase.
• Write menu instructions using this wording:

        On the File menu, click Save Project.
  

• When you give code examples, always use Visual Basic's default control and procedure names, such as Command1, List1, Option1.
• When you describe how to create a Visual Basic form, use complete sentences, and use the exact terminology used in the manual. Avoid using line-drawing characters in an article because of editing and interpretation problems. Instead, describe in complete sentences what controls go where and in what order.
• Use active voice and engage the reader by using the second person (you) instead of using "the user," "the customer," or "one." Use "user" only when it is necessary to differentiate the user from the developer.
• Use active voice such as: After you start Visual Basic, use x, call the y function, and click the z button. Avoid passive voice such as: After Visual Basic is started, x is used, the y function is called, and the z button is clicked.

  After writing your article, check for passive voice by looking at your use of the words have, is, and are. Where possible, change passive voice to active voice.

• Enclose error messages in double quotation marks, and be sure to quote the exact error message displayed on the screen by the software.
• Attempt to structure your article in a series of steps. There are many examples of this throughout the Visual Basic Knowledge Base.
• List all version numbers mentioned in the article to the hundredths place in the following section at the bottom of every article. This will satisfy all potential article-body queries in the online services.

Additional Knowledge Base Article Writing Guidelines

When you write an article, assume that the reading audience is just learning the product. Ideally, the article should be tutorial in nature and include complete step-by-step information. The goal is to help new users make use of the article. Write the article to stand on its own. Explain all underlying assumptions that the novice may not be aware of.

The 62-character (or shorter) title is one of the most important parts of the article. From the title alone, the reader decides whether he or she wants to read the article. The title should resemble a unique newspaper headline that sums up the contents of the article or describes or the symptoms of a problem or bug. All information conveyed by the title must also appear somewhere in the body of the text, because people often unintentionally separate downloaded articles from their titles.

When you include a code example, also include the necessary compiling, linking, and running instructions.

Please do not put tab characters into articles. Use spaces. Also, please do not put extended ASCII characters in articles submitted to BBoard. Use ASCII values from 32 through 126 only, and add a carriage return/line feed combination to terminate each line. Every line in your submitted article must end with a carriage return (CR+LF) at or before the 75th column.

Version Numbering Guidelines

In the special version number field at the top of the article (and in the .VERSION(S) field of the dot format for article submissions), list the product version numbers to the hundredths place (such as 1.00 for B_VBasic), and just list the numbers for that article's database.

But in the body of the article, please list product version numbers to the tenths (such as 4.0, 4.0b, 4.5). Only use hundredths for version numbers such as 2.01 which require hundredths.

In addition to the above standards, please list all version numbers mentioned in the article to the hundredths place in the following section at the bottom of every article (to satisfy all potential article-body queries in online services, where the separate version number field mentioned above is not included in article-body searches):