Wiki Life: Get to the point, keep it short!

As a general rule, people come to the Wiki looking for specific information, with a limited amount of time. They may be looking for information to help solve a problem, learn how to implement something, or to gain understanding and insight into a product. As an author, you have a few seconds (and possibly the first few sentences) to grab a reader’s attention, before they move on to another source of information.

Keep this in mind when you write an article. Do your best to keep sentences and paragraphs short, simple and concise. Get straight to the point of what you are trying to say. Remove sentences that don't add any value to the core subject of your article (see example below).

This will help to make your article clear and easy to read and understand. It increases the chances of your article being useful to the community (a very important article is useless if people don't read it!).

As an example, examine the following two paragraphs.

"People often get frustrated with SharePoint when they can't perform a task quickly via the UI (user interface). One such example, is updating multiple user profile properties quickly. Using the UI, there is no way to update the properties of multiple user profiles using a bulk operation. You need to select each profile individually, and update each profile one by one. This can be a slow process. Whether you're a SharePoint Administrator or SharePoint Developer, being able to quickly read, update or copy User Profile properties is a very handy skill to have. Using PowerShell to get and set User Profile properties is both quick and easy. It allows you to set properties on a single user profile, or a collection of user profiles. This article outlines how to do it!"

"This article outlines how to manage User Profile properties quickly and easily, using PowerShell"

Which paragraph is the quickest and easiest to read and understand? If all you wanted to know, was "What's this article about? Does it contain what I need to learn today?", which paragraph would you prefer to read?

When it comes to giving context (additional information) on why an article has been written, and what a reader should expect to learn from the article, be careful; There is a fine balance between giving enough information for the article to make sense, and giving too much information, which will make the article slow to read and harder to understand.

On that point, I've said enough! ;-)

Other Posts in this series: