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 (18)

  1. Durval Ramos says:

    Matthew, Very good tips!

  2. Dan Christian says:

    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.

  3. Saeid Hasani says:

    Right to the point! Thanks!

  4. Ed Price - MSFT says:

    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!

  5. Maheshkumar S Tiwari says:

    Matthew…..You nailed it 🙂

  6. Gokan Ozcifci says:

    Well done Craig!

  7. Matthew Yarlett says:

    Thanks for the comments guys!

  8. Matthew Yarlett says:

    Ps. Gokan, who’s Craig 😉

  9. Gokan Ozcifci says:

    Haha! Well, I don’t know.. I wanted to write Matthew; but wrote Craig! Sorry for that! =^)

  10. Matthew Yarlett says:

    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

  11. Anonymous says:

    Ctrl+C and Ctrl-X are one of the most used key combinations on my keyboard (only just out ranked by Ctrl

  12. Anonymous says:

    There is a saying, "A picture is worth a 1000 words". I'm sure you've heard the idea

  13. Anonymous says:

    Using code, markup or command examples in your Wiki articles can be very helpful to readers. Examples

  14. Anonymous says:

    You just finished witting an awesome article, what should you do next? Get up from your desk and stretch

  15. hassan sayed issa20014 says:

    Congratulations

  16. Anonymous says:

    Earlier this year I wrote a series of posts about writing good articles. It’s been a while since

  17. Anonymous says:

    Due to some practical issues while switching screens during presentation, the recording of the screen

  18. Anonymous says:

    Due to some practical issues while switching screens during presentation, the recording of the screen