Build a Better Table of Contents

Let's face it. The table of contents is probably the least sexy thing a tech writer does. And tech writing is by no means a sexy job. Nevertheless, I've been putting a lot of thought into tables of contents lately and in what goes into making a good one.

What's "Good" anyway?

A thing is good in as much as it lives up to what it is supposed to be, and, in the case of a functional thing, what it is supposed to do. A table of contents is a pretty functional thing and few people will ever enjoy a table of contents (TOC, to nerds like me). Even a really nice TOC. People just want to use it and leave it. Literally. So a good table of contents is one that does what a table of contents ought.

A good table of contents helps readers identify whether and where some desired content is so they can go on with their life.

Why Not Just a Search Engine?

Good question. Every docs portal of more than a few pages should have a search engine built in. The tricky thing about a search engine is that to use it you have to know what you are looking for and at least some of the search terms to help you find it. Readers who are brand new to a subject matter often do not know these terms. Likewise, if your product uses proprietary terms or common terms in unusual ways, readers won't know that from the onset. They need something else to let them know that your product can do X or that you have articles that discuss Y. They need to be able to find those quickly. After reading an article or two, your readers will probably be able to understand the concepts and terms of your product much better. This understanding will help them know what to search for. In the meantime, they need help. That's what the TOC if for.

Attributes of a Good TOC

A good table of contents should be well structured. That means:

  • User-oriented structure - The temptation is to organize content in an order that makes sense from the inside. Your readers don't have inside knowledge. Content and tables of content should be organized in a way that it answers user questions in the order they are likely to have them. Getting Started goes first for user manuals, Prerequisites or Before You Start for admin guides, and so on.
  • Not too long or too deep - If it's too long, your readers will give up trying to find content. Again, if your TOC has too many levels, readers will dig and dig but never find and soon give up. If your table of contents is 20 entries long and each entry has a subtree of 40 items spread over 6 levels, your users will never find anything. For that matter, neither will you. You'll end up sticking stuff wherever looks right at the moment without carefully considering the whole plan because you can't consider that much complexity with any easy. I call such tables of contents bushy because they are overgown and hard to navigate.
  • Use UI structures well - Drop-downs and other HTML features can be handy for helping keep irrelevant content out of a user's sight. If most users are not administrators, it might make sense to hide most administrators-only content in under a TOC entry called Administrator's Guide. Hiding the content until the user clicks the entry will keep them from having to see it and be distracted by it unless they need it.

The language you use in your table of contents should be helpful:

  • Clear, commonsense words - Avoid jargon, innovation. Remember, your reader may not know your organization's special terms yet. Don't use them right at the start.
  • Parallelism - Use the same format for each entry as much as possible. Doing so helps readers anticipate meaning.

The Internet is Not a Book

The nature of books is that they each have a first page and a last page. By extension, they have a beginning and an end. We might expect readers to move through them in that order.

Except, kinda.

In reality, it's more complicated than that. Busy readers have always thumbed through books, other than those intended for entertainment, to extract information quickly. Busy readers treat a title like Coding in Java more like a checkbook register than a novel. Savvy writers have always tried to make this approach easier. That's why textbooks have large headings and boldfaced keywords. With websites, it's even more complicated than that, but it can actually be easier.

Except to make it easier requires more from the writers.

Don't Include Every Topic in Your TOC

We've all had the experience of missing things hidden in plain sight. If you want to hide a topic from your readers, the best way that I can think of is to include it in the table of contents along with hundreds of other topics.

Not every topic needs to be in the table of contents. In this marvelous modern age, we have hyperlinks. We also have search bars. And we have browser-based bookmarks.

Try this strategy. It's extreme, but it's a start. In the TOC, only include top-level topics: Before You Start, Installing the Application, Managing User Accounts, Managing Store Locations, etc. Notice I omitted things like Changing User Passwords and Updating Store Inventories. You can tell right away that those topics are very granuar and detailed. After you have included only top-level topics, at the top of each of those top-level topics, include a mini-TOC made of hyperlinks that direct users to subtopics. Using this approach, you are also free to link to the same topic from multiple top-level topics. In this way, the granular topic Giving a User Access to a Store Location might appear in two mini-TOCs.

We don't want to rely on a search bar. But if you have a good search bar, you can help your readers use it by introducing them to your special jargon right in the introductory material of those top-level topics.

In another scenario, image if you have six topics about installation. That's fine. Just link the first one from the master TOC. Link the second topic from the first and back to it, as well as to the third topic and back from the third. And so on. At the top of such link-lists of topics, you might put some visual indicator to show your readers how many topics there are in the series and which one they are looking at.

linked-list-of-topics
It might be that some subtopics really do need to be included in the master TOC and not merely linked from top-level topics. Maybe you judge it will be hard for a user to know where to find it otherwise. That's OK. Just start with the principle that less is more.

Clutter hides important things among unimportant things.

By excluding these topics from a master table of contents, we can keep it visually accessible.

Think of Your User First and Last

Notice that I write user. Let me emphasize that most people who check out documentation don't want to read it, let alone read it all. They need to use the docs because the product wasn't easy to figure out. They're already annoyed. Don't satisfy your ego by making them read it all. Satisfy your ego by helping them do what they need to do.

Along these lines, your table of contents is not a list of all your achievements. A table of contents is a tool to help a user quickly find the relevant information and get back to their lives. Include what will help them. Exclude what can be done better elsewhere. Organize with your user's perspective in mind. They won't love you for it. They probably won't even notice you for it. But if they're paying much attention to your table of contents, you can bet they're not happy with you.

Comments: