Writing an Online Help Plan

The planning process is crucial to the online help plan. There are businesses that exist for the sole purpose of helping organizations develop effective planning processes. The key reasons for planning include ensuring fiscal responsibility, meeting deadlines, keeping project staff informed and goal-oriented, and designating and delegating roles and tasks.

The task of writing an online help plan can be completed by the documentation team leader, the writer, the editor, or by all of these people. Each have their own expertise and perspective.

An online help plan should::
  • Include a description of each phase of the help development process
  • Be reviewed and approved by stakeholders
  • Be updated as needed
  • Include a schedule that also includes links with the user interface development schedule
  • Address assumptions, dependencies, and risks

Eleven basic steps of writing an online help plan

There are eleven basic steps to plan an online help project.

1. Analyze the audience, plan the project, and write the plan. This step involves all of the following sub-steps:
  • Description of the software product and it's purpose
  • Analysis of intended users and tasks
    • Audience analysis
    • Task analysis
  • Study the competitor's products, previous software, or integrated systems
  • Develop specifications
    • High level
    • Detailed
  • Determine constraints
    • Operating system(s)
    • Limits on functionality
    • Compatibility with the product's documentation
    • Linking the help to the product
    • Translation into other languages
    • Localization
    • Budget
    • Time
  • Assumptions
    • Operating system
    • Review deadlines
    • Development schedules
    • Specification change process
  • Dependencies
    • Accuracy and completeness of technical specifications
    • SME (Subject Matter Expert) input
    • Availibility of working version of product code
  • Risk and mitigation strategy
  • Time estimates for planning, writing, editing, reviewing and testing
  • Negotiation to determine
    • realistic requirements
    • access to a working version of the software
    • the type and timing of technical reviews and testing
    • the final authority to approve the content
  • Choose communicators to write index, and edit the help
  • Choose professional usability experts to advise, evaluate and test the help
  • Choose a help-authoring tool and other required software
2. Develop high-level specifications.
  • Information types, topic types, window types, and navigation aids
  • Audio and/or video files
  • Develop a high level sample of the help for the client's approval
  • The help can be linked to the user interface consistently
3. Develop detailed specifications.
  • Writing conventions
  • Terminology
  • Style sheets
  • Topic templates
  • Back up strategy for personnel changes
4. Perform a detailed task analysis.
  • Use cases
  • User scenarios
  • Task list
5. Build and evaluate a prototype help system
  • Include at least one example of each topic type
  • Include all relevant navigation aids, links between topics, and other design components
6. Develop an outline and map of the help project.
  • Consider the following issues:
    • One application window may be used for more than one task
    • More than one help topic may be needed for one application window
    • One help topic may be reusable for more than one application window
7. Write, index, and edit the topics.
8. Review the help topics; this is usually done by the software developers or SMEs.
9. Test the help.
10. Release the help with the product.
11. Evaluate the help plan for improvements.

The table below lists each step, the benefits of completing the step, and the problems if the step is not completed.

Benefits of Completion
Problems by not Completing
Analyze the audience, plan the project, and write the plan
Complete the project on time and within budget
Produce usable, helpful, correct and complete help.
Creating unrealistic expectations
Develop high-level specifications
Everyone knows what is expected
Consistent help (where, what)
Easier to test
Easier to review
Inconsistency in design
Problems may be overlooked
Review and testing will be more time consuming
Scenarios cannot be adequately written
Develop detailed specifications
Stakeholders know what is expected
New members of the team can quickly come up to speed
Leads to inconsistency
Perform a detailed task analysis
Forms the basis of the help topics, and the editorial review of the index, the table of contents, and overall helpfulness
The writer may forget to include information, and the editor may fail to notice the omissions
Build and evaluate a prototype help system
Identify ideas that don't work well
Obtain feedback to improve the design
Some features may not work the way you intended
Develop an outline and map of the help project
You don't miss writing help for any windows, dialogs, or pages
Testers, editors and reviewers know which help topic is intended to be called from each window
Testers, editors and reviewers know what the internal links should be
Writers, testers, editors, and reviewers may miss some topics.
Write index and edit the topics
Indexes help users navigate the system
Consistent, error-free help looks and feels professional and users
are more likely to use the help system
Inconsistencies, grammatical errors, inadequate indexes, and unhelpful topics are not detected
The help will look unhelpful or unprofessional and users will tend not to use the help system
Review the help topics
Help is more likely to be accurate
Help is not technically correct
Help may not be helpful
Test the help
No broken links
No missing topics
Broken links
Missing topics
Incorrectly connected topics
Release the help with the product
Users can access the help system
Support requests should decrease
Loss of confidence in the help
Support requests increase
Evaluate the help and plan for improvements
Learn how to improve the help
Repeat mistakes

Weber, Jean Hollis (2004). Is the Help Helpful?. Frazier (Ed.), Planning an Online Help Project (pp. 1-11). Whitefish Bay WI: Hentzenwerke

Original Author: Linda Page
Contributors: Tammy Fitzpatrick
Editors: Mario Garcia, Sandra Ramirez, Larita Clow, Tammy Fitzpatrick