Wiki: What Makes a Great Wiki Article

Wiki: What Makes a Great Wiki Article

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. To find an idea of an article to write, 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. For example, be sure to include the task and the technology, tool or feature name. If needed for disambiguation, include the product or product version.
  • 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 article. Where appropriate, link to and from your article for ease of access. For example:
    • Link to the article from your blog or external site.
    • Link from the article to important supporting content in the Technet Library, elsewhere on Microsoft.com, or on external sites. 

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 presents 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.

 


Design Principles

An excellent article, in addition to appropriate and well-written content, also must follow a pattern of structuring and presentation of information. Each item of this pattern is described in the article User Experience Guidelines. However, you can always have in mind the four basic principles of design:

  • Alignment. Keep only one type of alignment on the text of the article. Note, for example, that throughout this article, the text is left aligned. Unaligned elements on a page are the sense of disarray. 
  • Repetition. The higher the repetition, the more the reader automatically identifies the content that he is seeking. This is a principle that helps to structure the content. Note that the repetition in the article ' how to make an excellent article in the Wiki ' was used in the following elements: 
    • The titles have the same pattern of presentation: Segoe Ui, 18, bold 
    • All the items in the lists are organized this way: Title. Description 
  • Contrast. Serves to highlight different elements. Note that the titles are in Bold and the font is larger than the rest of the text. 
  • Proximity. The relationship between the elements of a page creates the whole. In this way, how much closer are items related to each other, better readability. Imagine this text without any approximation of related content and without any formatting. 

 


See Also

 


Other Languages

This article is also available the following languages:
Sort by: Published Date | Most Recent | Most Useful
Comments
Page 1 of 1 (7 items)