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.

Download these templates to start

Acceptance Test Plan

Contingency Plan

Software Development Templates

Acquisition Plan

Conversion Plan

Software Requirements Specification

Action Plan

Cost Benefit Analysis

Software Testing

API Documentation

Database Design

Standard Operating Procedures (SOP)

Audience Analysis

Datasheet

Statement of Work

Availability Plan

Deployment Plan

System Administration Guide

Bill of Materials

Design Document

System Boundary

Business Case

Disaster Recovery Plan

System Design Document

Business Continuity

Disposition Plan

System Specifications

Business Plan

Documentation Plan

Technical Writing Templates

Business Process

Employee Handbook

Test Plan

Business Requirements

Error Message Guide

Training Plan

Business Rules

Expression of Interest

Transition Plan

Capacity Plan

Fact Sheet

Troubleshooting Guide

Case Study

Feasibility Study

Use Case

Change Management Plan

Functional Requirements

User Guide

Communication Plan

Grant Proposal

Verification and Validation Plan

Concept of Operations

Implementation Plan

White Papers

Concept Proposal

Installation Plan

Work Instructions

Configuration Management Plan

Interface Control Document

Software Development Templates

Acceptance Test Plan

Maintenance Plan

Software Requirements Specification

Acquisition Plan

Market Research

Software Testing

Action Plan

Marketing Plan

Standard Operating Procedures (SOP)

API Documentation

Needs Statement

Statement of Work

Audience Analysis

Operations Guide

System Administration Guide

Availability Plan

Policy Manual

System Boundary

Bill of Materials

Project Plan

System Design Document

Business Case

Proposal Manager Templates

System Specifications

Business Continuity

Proposal Template

Technical Writing Templates

Business Plan

Quality Assurance Plan

Test Plan

Business Process

Release Notes

Training Plan

Business Requirements

Request for Proposal

Transition Plan

Business Rules

Risk Management Plan

Troubleshooting Guide

Capacity Plan

Scope of Work

Use Case

Case Study

Security Plan

User Guide

Change Management Plan

Service Level Agreement (SLA)

Verification and Validation Plan

Communication Plan

Setup Guide

White Papers

Concept of Operations

Social Media Policy

Work Instructions

Concept Proposal

Contingency Plan

 

Configuration Management Plan

Conversion Plan