Do our docs really need a Table of Contents?

I’ve long been a devotee of table of contents (TOCs) in documentation, both online and offline. This was the accepted best practice, and I rarely thought much about it. After all, TOCs allow the reader to skim and do an efficient visual search for the information that interests them.

But I wouldn’t be writing this if I didn’t have some concerns about automatically including TOCs. Is it really necessary? Do readers use them, do they ignore them, or do the TOCs actually annoy them?

I’ve found that the answer is a frustrating “All of the above.”

TOCs for print

A book needs a TOC. A book also needs an index. But that’s because those are the search operations for ink-on-paper media, and are intended to be better than “flip through pages and hope something catches your eye” search operations.

PDFs are different: No, really, they are! You can search a PDF, and I’ve found that I, and most users I’ve talked to, use the search functionality when they’re looking for something specific. I will look at the TOC of a book when I start reading it, to get an overview of the contents. But once I start reading I rarely look at it again.

So a TOC at the front of a book is useful at least once, and doesn’t get in the way (or help, really) after that. So as long as it’s easy to create, it’s worth including. But it’s not worth spending days working on TOC formatting, worrying about whether to use lines of periods or blank spaces or something else to link a TOC entry and a page number, or waste time worrying about relative font weights of TOC entries. Trust me: Readers don’t care, as long as it’s better than a text crashing into one side of the screen (I keep seeing TOCs in Kindle books that didn’t survive the conversion process, but their broken bodies were left where they fell).

TOCs for online

For online documentation, I’m less certain. The typical tri-pane help includes a TOC by default, and I certainly have found it useful. But if I’m completely honest, I have to admit that I use search much more often than I scroll through a TOC. I do this with Microsoft help all the time, usually because I never remember how to deal with repeating table headers in Word. So I’m looking for a specific set of instructions, and I don’t want to know everything about tables in Word.

(I’ve already learned about how Word handles numbered lists, and that cost me enough sanity, thank you.)

Tech writers often bemoan this type of behavior: after all, we include conceptual information because it helps users understand why things work in certain ways. And those concepts will link to multiple procedural topics, and reading that series of topics will show the users all the cool things they can do with your product that they don’t know about because they didn’t read the manuals so they keep asking obvious questions and RTFM and aarghghghgh…

Ok, deep breath. I’ve certainly been there enough times, on both sides of the issue.

One example: I had an extensive reference topic for a product. In the TOC, it was two places away from the overview/intro topic about that product, which I knew had a lot of page views. But I didn’t suspect that anything was wrong until 4 months after I wrote those topics, a customer success rep asked me if I was ever going to document reference info.

“But…it’s there!” I said, showing her the topic.

She’d never seen it. NO ONE on her team, or in customer support, had seen it. I pointed out that it was right there, in the TOC.

“I never read the TOC,” she said. “I didn’t even notice it was there.”

When I’ve talked to users of the documentation sites that I’ve created, I consistently find that many readers don’t use the TOC. One problem is that many web-savvy users have been trained to ignore sidebars. That’s where the advertisements live, after all. So they concentrate on the middle section, the place with the blocks of text and pictures and videos and stuff.

Another problem is that the TOC quickly becomes cluttered. A flat list of topics quickly grows long enough to scroll off the screen; subtopics and sub-subtopics force users to expand branches, which just makes things more confusing.

Users do not want to understand your site like you do; anything more than a single level might as well be a labyrinth. And because they’ll instantly forget how they navigated to that topic, the TOC isn’t useful as a way for readers to learn the structure of the doc set. Again: not that they should have to, or want to.

Plus, the obvious string they have to find their way back is a “home” or “front page” button, whipping them up through the levels and forcing them to navigate that path again. So just assume that they’re going to land on any page either via search or blind luck, and give them plenty of obvious links to related topics.

TOCs and mobile

That’s a negative view, and I admit that some users do find value in help TOCs. But usually only when they stick to a single level of topics, and don’t force the user to expand and explore sub-levels. And the TOC takes up a chunk of screen space; on phones and tablets, it’s a significant portion of the screen, and the individual TOC listings are difficult to select with an imprecise finger.

I’ve been frustrated trying to navigate one of my own help sites on a tablet. I got an earful from internal users who tried it once and gave up. Which means that there were frustrated customers, too.

It could be that I’m just a bad designer, and I’ll admit there’s some truth to that. But I’ve had the same frustrating experiences with other help sites.

It’s often much easier to search for a topic, scan the list of results (assuming it’s a worthwhile list), and then start reading. Maybe it takes another hop or two to find it, but trying to use a long help TOC on a mobile device feels about as useful as spinning the Wheel Of Help and hoping for

Site vs. topic

I like topic TOCs: a list of headings in the topic, placed at or near the top of the page (maybe after an introductory paragraph, maybe at the top of the page). I used to use them all the time, but I’ve written too many topics where they don’t work well.

They don’t work well when:

  1. The topic is too short (and the contents are obvious)
  2. The topic is too long (and the TOC pushes the content off the screen)

Which leaves that “just right” topic where they aren’t useless or overly intrusive. The answer might be to strive to write topics that fit that “just right” length (or just number of headings), but a goal to write a topic so it generates a pleasant TOC is completely ridiculous. And including a TOC on some topics but not others would trigger my Tech Writing OCD and gnaw at my soul.

Conclusion

Tri-pane help, with the left-hand TOC, is what I think of as “generic online help style.” It looks old-fashioned, and I assume that it’s information that used to exist as a book and was dumped into an online help template. I assume that because I’ve seen it too many times: The content reads like a book, and isn’t really suited for online use.

I used to love TOCs, and I do think they’re useful. But in moderation: Clean, single-level, without expansion into a maze of subtopics. Even better is to build your documentation as if you don’t have a TOC to fall back on. Because once they land on a topic and start reading, they aren’t likely to skip back to the TOC and navigate the topic tree again (if they did that in the first place) in the hope that they’ll find something useful. Add lots of links in the text, Related Topics sections, Next Steps, See Alsos…whatever will guide your reader to more, relevant information. No one wants to learn your doc structure, and forcing that on your readers will send them fleeing back to Google in search of answers.

Advertisements

3 thoughts on “Do our docs really need a Table of Contents?

  1. Agree completely. There definitely is a need for some form of top-level categorisation of content, not only for navigation but also for allowing users to see areas of a product they may not know about. TOCs are not really needed for those times when the user searches for a specific term, but there are still some users who will just want to know what else a product can do.

    I think the old-school TOC will soon be a thing of the past in online help, but there will be some other form of top-level navigation. Even if it is only buttons for general categories or css menus.

    1. Thanks, Craig. I think you’re right about a new form of top-level navigation. I’ve also seen good examples using buttons and CSS, as you said, and I really think that’s the way forward. This is a good example: https://reference.wolfram.com/language/

      I didn’t even touch on usability, and tiny-font TOCs with small click zones for expand/collapse are an accessibility nightmare.

  2. I cannot agree more. A majority of organizations plan the structure of online manuals around the taxonomy, or they follow the modular approach to categorize the information. Once classic example is the harvest help available at: http://www.getharvest.com/help. This is so clean and easy to reference as an online manual.

Comments are closed.