The hardest part of any project is getting started. With that in mind, I’d like to share my tips and tricks for structuring a Help system for a software application. The structure is suitable for manuals also, so you won’t have any issues if you are single-sourcing. This method will also work as a guideline to evaluate an existing project.
When structuring a Help system remember:
- Help is architected much like a website. (It has all the same basic pieces: a TOC, Navigation, Topics, Search, etc.)
- Well structured Help projects start with well structured topics. (F0r information about structuring topics, see How to Structure a Help Project, Part 2.)
Five Steps to Structuring Help
There are five steps to structuring your project, but you don’t have to do them in order. In fact, you should do 1-4 concurrently. This method will work in Agile shops; you’ll just drop your content each iteration, and design the Table of Contents incrementally.
- List Functionality
- Review the UI
- Collect the “housekeeping” topics
- Determine reference resources
- Design the Table of Contents (the architecture)
#1 List Functionality
You can gather a complete list of product functionality by working with subject matter experts (SMEs), reading requirements documents/Internal documents, meetings, working with the software, books/articles/blogs, and the company website.
When writing the documentation, remember to use the language of the user — avoid jargon when possible.
#2 Review the User Interface
A UI review will give you a complete inventory of UI elements — and in what context they will appear. A subset of your inventory will be the UI elements (generally dialog boxes) that will need context sensitive Help.
The level of UI documentation included in your final project will depend on the complexity of the interface itself, as well as other factors. For example, since Doc-To-Help includes a Dynamic Help pane, Help topics had to be included for each UI element (ribbons, windows, accordion panes). When users navigate around the interface, Help is displayed immediately in the Dynamic Help pane.
You can do a video “tour” of the UI, but make sure the help links to it.
To get started:
- Determine which UI elements need to be explained (Ribbons, Buttons, Windows, Panels)
- Find every dialog box. Note which ones have Help buttons. (If a dialog box needs a Help button, but doesn’t have it, file a feature request.)
#3 Collect the “Housekeeping” Topics
Every application has “housekeeping” topics that must be included in the project. After this list is determined, you can consider putting some items that change frequently (such as EULAs) on the web and simply link to them.
Common “housekeeping” topics:
- System Requirements
- Technical Support options
- Trademark Statement
#4 Determine Reference Resources
For some applications, including additional types of reference materials in your Help project will make it easier for users to learn and use your software. These materials can be included within your Help project, or delivered separately — but make sure anything delivered separately is mentioned within the Help project and linked.
Reference resources can include the following … think about what else would be useful to your users:
- Quick Starts
- Code Samples
- Sample projects
#5 Design the Table of Contents
Even though the TOC may not be the primary navigation method for some users, it does provide the architecture for the project, and users will discover it via search. Your TOC will also help you to logically develop the “See Also” or “Related Topic” links included in each topic.
To begin, start with the four “buckets”:
Then start designing:
- Structure each bucket separately.
- Group topics within each bucket, then name each group.
- You might want to try a card sort. (See this video to learn more.)
TOC Design Notes
- “Functionality” is the most difficult category to structure. Some options include:
- Order of performance (if application is strict about this)
- Most popular (often used) to least popular
- Order of importance
- Build your TOC in a spreadsheet. Make sure to flag the topics that are also the context-sensitive Help. Include everything in the spreadsheet, although you may not be able to deliver everything in the first release. Consider the inverted pyramid when deciding what topics to include.
- When naming topics, avoid using the name of the dialog box in the title. This is not helpful for users (unless the dialog box is intuitively named, in which case … use it). If your Help is posted on the web, this practice can also affect search engine results and SEO.
Here is an example Table of Contents:
This structure scales for a TOC that includes multiple products; you just need to add two more categories:
- “Overlapping functionality” — topics that are relevant to all products.
- “Consolidation fuctionality” (if necessary) — topics that explain how to combine the products.
Each of the individual products in the “Product” bucket would include the functionality topics for each product.
OK … So What’s Next?
Now that you have your structure, it is time to start writing. As I mentioned earlier — well structured Help projects start with well structured topics, so see this blog post to learn more about topic types: How to Structure a Help Project, Part 2.
Good luck with your projects!
Additional Resources and Further Reading
Laying the Foundations for Success by Nicky Bleiel, ISTC Communicator Summer 2010
Bringing Help to the Forefront: Strategies to Increase the Usability of Your Software User Assistance and Your Product by Nicky Bleiel, STC Intercom June 2009
Information Architecture Tutorial (Webmonkey)
Technical Writing 101 by Alan S. Pringle and Sarah S. O’Keefe
STC Intercom January 2012 Special Issue: Information Architecture