Revision #20

There are many ways to write a Wiki article.  This topic describes what works best in Wikis like this one.

To post an article, click the link on the right or click here.

How to Make a Great Wiki Article

A great Wiki article provides one or more nuggets of information needed by the reader based on the title and first paragraph. If you promise to describe how to deploy a certain feature in a particular environment, your article should concisely and succinctly describe the environment and preconditions, list the steps, and describe the end state with diagrams, videos, and other supporting material as needed so that the reader can complete the task.

To create a great Wiki article:

• Identify the one or two key nuggets of information you want to share.
• Lay the ground work for the nugget in the title: How to verb the <nugget>, Troubleshooting <nugget>, Connecting <nugget> to <other product>, Getting Started with <nugget>, etc.
• Set expectations for the article in the opening paragraph. Will you be walking through an installation of SQL Server 2008 into a clustered environment using a cluster of 64 bit machines, describing the peculiarities of interop between two features, discussing the pros and cons of calling one API function over another, providing troubleshooting steps for a product or feature, or discussing the general features of a certain implementation? Readers want to be told what to expect.
• Write concisely. Longer articles are not better articles. If you can provide your nugget of information in 20 words, then 20 words is enough. 
• Use your own style, but not at the expense of clarity. We are not all robots. Use your own style, but do not let it get in the way of what you are trying to say. Protect the information nugget!
• Use keywords about the nugget in the title and body. No fancy search engine optimization stuff, just know your keywords and use them.
• Provide references where needed. Reference provide credibility, authority, alternative views, added details, and often enhance the reputation of the article.
• Have and express an opinion. If you prefer a specific deployment solution, describe the alternatives you explored and why you have the preference. Like one way of calling an API function over another? Tell us why! Tell us about the things you tried that did not work. It may seem trivial to you, but we, the readers, want to know.
• Ask for the help you want. If you want people to add additional scenarios, scripts, or other information, let them know.
• Contribute boldly, edit gently. You may be the creator of the article, but once published the community owns it. If spelling and grammar are not perfect, the community will eventually step in and nudge it.
• Connect the articles. Where appropriate, link to and from your article for ease of access.

If you fill a need, readers will find your article.

Types of Articles

Your article could fill many different types of needs. Here are a few types of needs that you might find:

• Discussion. This type of article presents different options, opinions, and points of view. If readers disagree with some point, then they add their own thoughts and considerations as an “Alternate opinion” to the existing opinions. The goal is to clearly present all the perspectives. Examples.
• High-level Overview. The purpose is to give a basic overview of a product, theory, or general concept. If large subsections are forming, start a new article and link to it. Examples.
• How To. This type of article presentes instructions that are as clear and simple as possible. Example: How to Add a Video or Image.
• Stub. A short article you start that will need expansion. Create a stub. Maybe you don't have the time or knowledge to write the full article, but you hope to complete it later or that the community will complete it. Examples.
• Link Collection. An article that is mostly a collection of links. This could be a wiki portal (where all the links are to other topics in the TechNet Wiki) or a collection of external links (or a combination). Make sure it is clear whether or not the links are to other wiki articles. Examples: Getting Started, List of Products and Related Topics.
• Troubleshooting. A list of solutions for common problems when interacting with a specific product or interface.  Examples.

See Also

• Getting Started

Other Languages

This article is also available the following languages:

• Wiki: Qu'est-ce qui fait un article Wiki réussi (fr-FR)