Overview topics play an important role in creating a positive user assistance experience. Unlike procedures, which deliver critical information on how to solve a problem quickly, overview topics fill in the conceptual details and background "story."
Here are some tips for writing thorough and informative overviews.
- Stay focused. The goal of the overview topic is to provide a broad picture of a single concept. For example, "Overview of printing." Such a topic might provide information on when the print functionality is available, what role printing plays in the overall use of the software, and so on. It should NOT cover information on a different concept, such as editing documents.
- Include a generous helping of hyperlinks. Overview topics should provide only the big picture, but they should link to all of the details. Your "Overview of printing" should include links to "Printer setup," "Changing print options," and other related procedures. You should also link to FAQs, troubleshooting tips, and any other granular topics related to printing.
- Include plenty of subheadings. Usability studies show that readers, on average, only look at roughly 30 percent of the content on a page. The use of subheadings allows them to skim effectively to find the information they need.
- Consider internal navigation. Long topics may benefit from a table of contents or some mid-topic anchors to allow users to navigate within the page. A long overview can make for tedious scrolling, so linking within the same page can make for a more pleasant user experience.
- Keep paragraphs short. Research shows that readers prefer shorter paragraphs when reading digital content. A few sentences per paragraph is optimal, so you may need to break longer paragraphs into several short paragraphs.
- Follow Strunk and White's advice and "Omit unnecessary words." Carefully consider whether your content can convey the same important information in less words. Remember, users access the help when they are frustrated. Don't make them read the equivalent of "War and Peace" to understand the role of printing in your software. If a sentence doesn't contain need-to-know information, strike it.
- Use the word "overview" in your topic title. Users should be able to skim the titles in your table of contents, index, and full-text search results and quickly identify whether a topic contains overview information.
- Create an outline before you start writing. This will ensure that your resulting topic is thorough and covers all facets of the concept. If you can, have a fellow writer or an SME perform a peer review of the outline to verify that you haven't missed anything.
If you follow these guidelines, your overview topics will be informative and highly usable.