Skip to Knowledge Base content

"How To" Article Example

A how to article guides the user through a detailed set of instructions about how to complete a task. How to articles may be long and complex and may contain several steps or even several sets of steps. The title should say "How To" in the title. Example: "How to Weave Baskets Underwater". To ensure user trust, comfort and familiarity with our self help solutions, use this formatting and section order when writing a how to article for the OIT knowledgebase.

When to Use Which Headings and How (this is "heading 2")

"Heading 2" uses a horizontal line after the text to create a logical break between paragraphs - which is very good for visual organization. When you have topics that all relate to one another very directly, but all fall under the same heading - use "Heading 3" as the sub-heading title. Examples appear below in this article. When typing headings, use camel case (ex. "This Title is Written in Camel Case, also Known as Title Case"). The only exception to this rule is when writing a FAQ. When using Heading 3 for FAQ questions, use proper, or sentence case (ex. "This is proper case, also known as sentence case").

Introduction (use "Heading 2")

This section should be one to three paragraphs describing the product and what this article is designed to help the user do. Remember that we always want to write articles in a customer friendly voice, using vocabulary that the user will readily understand.

Estimated Time to Complete (use "Heading 3")

How long should a user expect to spend following this guide? Consider that if it takes you 3 minutes to do something, a user will likely take longer. A how to guide may be a complex and involved set of steps or procedures that could take up to an hour. If a how to article will take less than 15 minutes for the average user, consider writing a quick start guide instead.

Vocabulary (use "Heading 3")

If there is any special vocabulary that users absolutely must learn to be successful, list those words here. This should be very rarely used. If you aren’t going to use this special vocabulary, don’t add the section to your article.

Special Concepts (use "Heading 3")

If there are any special concepts that users need to learn to successfully complete this how to guide, list those concepts here with a brief, customer focused, simple language description. If you aren’t going to use any special concepts, don’t add the section to your article.

Steps (use "Heading 2")

Numbered lists should be used for anything that has steps that are dependent on the previous steps for completion or to show prioritization of or levels of importance. Bulleted lists are used for information that is non-prioritized, but still falls under the same logic.

  1. Steps should be numbered and written in order to help the user understand what is happening and what is happening next. And what is expected of them
    1. Sub-steps should also be in order and either numbered or lettered
    2. So the users can understand what they are doing
    3. And what is expected of them
    4. And what is coming next
    5. If you need more than sub steps reconsider the breakdown of your article
  2. Steps should be numbered and written in order to help the user understand what is happening and what is happening next. And what is expected of them
  3. Steps should be numbered and written in order to help the user understand what is happening and what is happening next. And what is expected of them
  4. Steps should be numbered and written in order to help the user understand what is happening and what is happening next. And what is expected of them
  • This is an example of related thoughts that have no priority
  • When you have a list of related thoughts, numeric lists are ill advised
  • Using bullets should be used as mentioned before for non prioritized lists
  • Bulleted lists also work for for non-ordered lists
    • Sub-bullets can help organize further
    • If you need another level of bullets beyond sub-bullets, reconsider your article's organization
  • Bullets are inappropriate for a series of steps that a user needs to follow.

Conclusion (use "Heading 2")

Remind the user what they just did, and how the results of this process should have helped them.

Additional Resources (use "Heading 2")

If appropriate, add this section to the article to explain how to get additional help or where other resources may be found for this topic if needed. If other articles cover this elsewhere in the knowledgebase, consider adding article links at the top of this page to allow users quick access to them. You can also attach related helpful documents if necessary. These can be printable PDF's of the article you have written here for those types of articles that require a user to be offline while working.

Was this helpful?
0 reviews

Details

Article ID: 32431
Created
Thu 6/22/17 3:01 PM
Modified
Thu 6/29/17 8:28 AM

Files (1)

docx

How to.docx

6/22/2017 3:45:51 PM