Technical Writing Tools: Help Authoring

Technical Writing Tools: Help Authoring

*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

The most common reason for a user to look at an online help file is to find an answer to a specific question. The most important aspect of a help file is accessibility of the information it contains. Help files range from small, simple “read-me” files with very limited information to hypertext-based documentation.

First Steps

  • Identify topics: Help files are designed to work in conjunction with other types of documentation to form a complete information package. It is the task of the developer or technical writers to identify the help file topics. The best way to do this is to analyze the product. Then, once you have identified all of the topics, separate them into related groups.
  • Create a structure: Once you have identified the topics, you can start structuring the help file. Although the structure can depend on the software, the main purpose of the help file is to provide quick access to specific information. You can achieve this goal by using a simple content tree and keywords to build the help file index. Typically, the content tree should not exceed three nesting levels, although you can use two levels for small files that contain short topics and sub-topics.
  • Design: Design a structure that does not change often, even if information for a specific topic changes. Create a modular and flexible help file that can be used for the next version of the software. The HTML file names should remain stable. If the help tool allows it, it would be good to have a method of differentiating the various HTML files of the same name.

Creating a Help File

  • Access: A help file is not read in the order it is written, so make sure the most important information is accessible from accessing it in multiple ways. For example, the introduction page might never be read, while other information might be accessed by the index directly without the use of the content tree. If a specific topic is discussed in another part of the file, create a link to help users access the related page.
  • Content: The most important part of a help file is its text content. Even if you use graphics and formatting to make a point, the help file will be ineffective if the text is limited.
  • Hypertext: Provide links for users who are interested in knowing more about a specific topic. The most important rule is to make sure the links are actually relevant and useful. With this in mind, it is probably better to use too few links than too many.
  • Keywords: Prepare a list of keywords that are related to the specific HTML pages of the help file. Some users like to browse through the content tree, but others go directly to the index to find the topic by keyword.
  • Size: It’s not a good idea to create a smaller file by limiting the information included in it. A help file should contain everything necessary to use the software and solve simple, typical problems. This means the size of the files can vary from very small to 15 MB and more.