Latest posts by techwriter (see all)
- Test Your Knowledge of 4 Basic Fonts – Drag & Drop - January 27, 2017
- How NOT to Design a Web Site - January 25, 2017
- Hazards of Poorly Written Technical Documentation - December 26, 2016
© Ugur Akinci
How would you organize a Table of Contents (TOC) when documenting software?
What’s the best way to do that?
A common beginner’s mistake is to compile a TOC by such GUI (Graphic User Interface) components as tabs and menus.
For example, let’s say you are documenting how to use MS Word.
One way to organize your document is to create a chapter for each of the tabs on the Word ribbon:
You certainly can have a TOC that looks like this:
- Page Layout
But I’d recommend not to do that. Why?
Users rarely want to learn how to use a software because they are curious what different tabs and similar GUI components do. They rarely tell themselves “I need to learn those Word tabs today.”
Instead, they have a PROBLEM to solve and they try to teach themselves how to SOLVE that problem.
For example, a user would try to find the best way to create a Footer. And to do that, she needs to use the Insert tab. When you describe how to use the Insert tab in order to answer the more general question of creating a footer, then it becomes a significant piece of information. It becomes relevant and earns a justified place in your TOC.
Thus I’d recommend a more solution and procedure oriented TOC like the following: