How to Structure a Software TOC — by GUI Components or Functions & Processes?
© 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:
Tabs:
- Home
- Insert
- Page Layout
- References
- Etc.
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:
Headers
- Creating
- Editing
- Deleting
Footers
- Creating
- Editing
- Deleting
Etc.
