Documentation and the Case for Better Navigation

online_vendor_documentation

Some of these ideas are from Mark Baker’s blog, Every Page is Page One.

The first challenge of documentation is to get the user to use the product. It doesn’t matter how usable it is if it is so off-putting in appearance that no one tries to use it.

Some of the things we document are complicated, but it doesn’t mean that every individual task, feature, or concept needs to be complicated. Throwing all the content in the user’s face when they look for help with something simple is distracting. It only serves to discourage users from trying and learning.

Take the classic tri-pane help system. It may be full of utility–multiple ways to view and navigate the content, multiple buttons to push to move around it in different ways. But, it screams “Look how big and complicated I am. Look at how many pages there are. Look at how deep they are nested. Look at all these controls you will have to use to navigate me!”

A PDF is far less usable than a well-organized online help system, but it is actually clearer. It presents a single pane and a search box, and everyone knows how to use a PDF. Videos are even better, but they are lousy for many tech comm tasks — tedious, impossible to navigate, impossible to search, impossible to use for reference— but their entire interface is a single triangular button. No wonder users ask for PDFs and videos even when they are not appropriate or usable. They just look so much better.

With the web, the user is not restricted to a TOC or index — you can offer relevant links on every page that allow them to move effectively through the content without ever being aware of how extensive it is or how complex the product is. If they want to explore any of the topics, they can do so simply by clicking a link. Each topic is a navigation hub.

Adopting this view of organization is important because as our content becomes larger and more dynamic, it becomes more and more difficult to navigate using a fixed table of contents. Seeing everything at once is too overwhelming or general, and artificially segmenting it is too confining.

With the web model, you can create documentation that looks simple while remaining thorough and comprehensive in the depth of its coverage. This way, you can have a large information set with manageable navigation at every point, but still have the ability to travel very far across it.

 

Technical Writing Tools: Help Authoring

HelpButton

*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.

Have something to add? Please share it in the comments.

Some Best Practices When Writing Help Documentation

writing-help-online

*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.*

If you are planning to create online help documentation and want to make sure you end up with one that is truly helpful, here are three best practices you can follow to make sure it is:

  • Tailor it to users who have with varying skill sets and goals.
  • Review, test, and update it for accuracy.
  • Create context-sensitive topics.

Keep different users in mind

You can’t always predict what every user will know or want to know about any product. On one hand, if you oversimplify help steps, users might get confused. If you provide too much detail, they might get frustrated or bored.

One way to alleviate this problem is to divide help topics into several different types that target users at different skill levels by varying the kind and amount of information you provide. For example, you might have an overview topic, such as a definition of a specific system function, and then provide a link to all of the tasks related to that function within the overview. That way, users get just the specific steps they want.

The key is to allow users to navigate the help documentation to find (or avoid) as much detail as they want.

Continue reading