Sample Guidelines for Writing Online Help

If you’re looking for guidelines to write your online help documentation, then use this checklist to get started.

How To Write Online Help Documentation

Help is required for every web page. Each help page should:

  • Provide a brief introduction.
  • Describe the primary tasks supported by the web page
  • Provide step-by-step instructions for completing these tasks
  • Include tips, notes and shortcuts

How to Write Online Help

When writing, anticipate questions users might have when using a web page. Put yourself in their shoes. Then, seek to answer those questions.

Think about what information they need to complete the task successfully, and try to provide that information.

Add Value – Please do NOT just reword information already clearly expressed on the user interface. Think about the task the user is performing, rather than just describing the interface.

Try to provide a user with answers to the following questions:

  • When or Why should I use this web page?
  • Explain the benefits of using the web page.
  • How do I use this web page? Give step by step instructions.
  • What do I need to know / do before using it? What happens after I use it?
  • What are the consequences of selecting one option from a list instead of another or clicking one button instead of another?
  • Explain the benefit of using this screen to the user.

Give examples: For example, describe why a choice, displayed as unavailable, is unavailable and how the user can make it available.

Online Help Template

Use the following template to write the online help for your web page.

Most web pages require a Title, Purpose, and Instructions as a minimum.

Where appropriate you can include prerequisite information, what the user needs to do next, as well as notes and tips that help them perform their task. Use your own discretion. Some web pages are very straightforward, other requires more detail.

  • Author Name
  • Webpage Title
  • Section #
  • Purpose: Describe the purpose of this web page from the user’s perspective. Write 1 or 2 sentences that explain its main purpose, usefulness, and the expected outcome or result.This web page allows you to…
  • Prerequisite – Identify prerequisite conditions or tasks that users must perform before beginning this task.

To use this web page, ensure that you have etc…

  • Instructions – Provide step-by-step instructions that describe how to complete the task(s). To sort the task-list, follow these steps:
    1. Do this
    2. Do this
    3. Do this
  • What’s Next – describe what happens next? What happens after the user performs this step (e.g. outcome; results and follow-up information)
  • Notes – Highlight the effect, other options, or issues that may arise by performing this step.

Other things you need to highlight are shortcuts, right-mouse options, or other pieces of information that make the task easier to perform.

Those are some ways to get stared with online help documentation.

How do you get started with these projects and how do they differ from traditional hardcopy technical documents.