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:
Comments
- Anonymous
January 22, 2014
Matthew, Very good tips! - Anonymous
January 22, 2014
Hi Matthew,I am in full agreement with your suggestions. A brief synopsis (or introduction) + TOC definitely helps. In my opinion, adding more contents to the TOC isn't a bad thing.Also when I start a new section, I break it into separate paragraphs with the opening sentence giving a brief description of it. - Anonymous
January 22, 2014
Right to the point! Thanks! - Anonymous
January 22, 2014
Unless you're writing a long, epic article like Matthew does: http://social.technet.microsoft.com/wiki/contents/articles/21801.sharepoint-a-complete-guide-to-getting-and-setting-fields-using-c.aspx -- Seriously though, long is fine, as long as you are moving on to the next topic like Matthew mentions in this blog post. Also, another counterpoint is that I find a lot of articles that need more explanations of new ideas and of what code snippets are doing. But even then, short and direct explanations are best. Thanks Matthew! - Anonymous
January 22, 2014
Matthew.....You nailed it :) - Anonymous
January 22, 2014
Well done Craig! - Anonymous
January 26, 2014
Thanks for the comments guys! - Anonymous
January 26, 2014
Ps. Gokan, who's Craig ;-) - Anonymous
January 27, 2014
Haha! Well, I don't know.. I wanted to write Matthew; but wrote Craig! Sorry for that! =^) - Anonymous
February 06, 2014
My latest article is testament to what Ed pointed out, that the "keep it short" bit mostly refers to keeping sentences and paragraphs short and simple to read! http://social.technet.microsoft.com/wiki/contents/articles/22864.sharepoint-create-2000-domain-accounts-with-profile-photos-for-a-development-environment.aspx - Anonymous
February 19, 2014
Ctrl+C and Ctrl-X are one of the most used key combinations on my keyboard (only just out ranked by Ctrl - Anonymous
March 05, 2014
There is a saying, "A picture is worth a 1000 words". I'm sure you've heard the idea - Anonymous
March 16, 2014
Using code, markup or command examples in your Wiki articles can be very helpful to readers. Examples - Anonymous
April 02, 2014
You just finished witting an awesome article, what should you do next? Get up from your desk and stretch - Anonymous
July 17, 2014
Congratulations - Anonymous
August 20, 2014
Earlier this year I wrote a series of posts about writing good articles. It's been a while since - Anonymous
March 19, 2015
Due to some practical issues while switching screens during presentation, the recording of the screen - Anonymous
March 19, 2015
Due to some practical issues while switching screens during presentation, the recording of the screen - Anonymous
September 08, 2017
good tips