back to CATS home

Knowledge Base

Steps to Create a How-To Knowledge Base Article

(Modified from Apache and evolt – see Resources)

Write the Overview

State the point of the article in two or three short sentences with virtually no detail.

An overview helps potential readers quickly determine if your article matches their interests or needs. Make sure to include any critical definitions that will help readers evaluate the usefulness of your How-To. Consider writing the overview last, after you have completed all other sections. If you have trouble with the overview, synthesize your How-to by answering these questions in two or three sentences: "Who does what to whom (or what), when, where, how, and why?"

Describe your Intended Audience

If your How-To is targeted at a specific audience, describe it here.

For example, potential readers will have different levels of skill with equipment for smart classrooms. They will also bring different areas of expertise and backgrounds to their How-To learning experience.

State the Purpose

Tell your audience what value they'll get from reading the article.

List any Prerequisites

What do they need to know to understand the meat of the article?

Tell your reader about any required knowledge, configuration, or resources they may need before stepping through your How-To. Link to other useful resources on the CATS Knowledge Base or other websites.

Describe the Steps of your How-To

Describe exactly how readers can reproduce your results, one step at a time.

Walk your reader through the process step-by-step. Make sure s/he can reproduce your intended result by following your exact steps. Supply sample code snippets or configuration details as necessary.

Add Examples and Applications

Explain the practical application in more detail, including examples if possible.

Provide a few real-world examples of how the techniques or capabilities gained from your How-To could be applied. Reward the reader for successfully completing the How-To with a few ideas about how it will pay off.

Summarize the Entire Process

Reinforce the main points of your How-To in a few sentences.

Additional Tips or FAQs

In some cases, step-by-step instructions simply aren't enough. Use this section to pass on any other tips or answers to frequently asked questions. Anticipating the needs of your readers will increase the overall success of your writing effort.

References/Bibliography/Notes

Remember to acknowledge any third-party resources or individuals who contributed to the development of your article. Some readers want to learn more, so consider providing links to more information, resources, or other materials you’ve used to derive your content.

You must be logged in to save your changes.

Login