What’s Hiding in Your TOC?

One of the defining characteristics of an Every Page is Page One topic is that it has no sequential or hierarchical relationship to other topics. There are no previous, next, or parent links in an EPPO topic, though there may be many links to topics on related subjects.

One of the objections I often hear from writers is that sometimes they need to create a defined order of topics because that set of topics forms a workflow. The question I ask in return is, if there is a workflow here, shouldn’t you have a topic describing that workflow explicitly?

A workflow is to important to be expressed only by the table of contents.

A workflow is a pretty important thing for many products. If the workflow is only expressed through the sequencing of topics, and is not otherwise being made explicit, the only thing that is really expressing the workflow itself is the table of contents.

I’m pretty sure that is not a good thing. I’m certain it is not a good thing on the web, where people will generally land on your content as a result of a Google search, and therefore will not have seen or used the table of contents. I’m pretty certain it’s not a good thing in an online help system either, where the reader may come to the topic via the search or index rather than the TOC. And I suspect is not a good thing even in a book, where, even if the reader does begin by browsing the table of contents, they will probably not recognize that certain sections of the TOC are describing a workflow.

No matter the medium, therefore, I think a workflow should always be described in a fully explicit fashion in a topic of its own. Since workflows generally consist of multiple tasks or procedures, a workflow topic can refer to those tasks and procedures and link to the topics that describe them. There is no reason why the workflow topic and the various procedure and task topics cannot exist as Every Page is Page One topics, and a number of good reasons why they should.

Workflows are not the only thing that can lie hidden in your TOC. I have seen manuals in which there is no system overview topic. If you wanted an overview of the system, your best bet would be to read the first paragraph of each chapter in the book. The organization of the book, in other words, expresses the overview of the system. Once again, important information is being expressed only through the TOC.

(Often, I think, a naive reading of minimalism may lead people to delete the system overview, on the grounds of lessening the time before the reader is invited do something with the product. But while minimalism tells us the people don’t generally want to start with a system overview, that does not mean they never want one. The desire to grasp the system as a whole usually comes later, as one develops mastery. But since bookish practice generally says that the overview should be at the beginning, the expedient of moving it somewhere else may not occur to the writer. On the web, of course, it is the reader who chooses the starting point, so location is moot.)

Even in the book world, having the TOC, or, more generally, the order of topics, carry part of the meaning of the work seems to me like poor information design. For it to work at all, the reader has to actually read the TOC and read the book in order, and in a fairly short period of time. Even if they do all of that, I’m not convinced that the typical reader would recognize or grasp the meaning implied by the order of the work. A table of contents is an instrument of navigation, not a carrier of meaning.

In a help system, or on the web, I’m certain that any information or meaning implied by the order of topics, whether linear or hierarchical, is going to be lost on the reader, who is generally accessing the content at random.

Technical communications, in any case, is not a field where meaning should be left to implication. If there is some information that the reader needs, it should be explicitly stated in a topic, not implied by a TOC or by the order of topics.

I also fear another pitfall when the TOC or the order of topics is made to carry meaning. By not explicitly stating the workflow, or the system overview, or any other information being implied by the order of topics, the writer may hide from themselves the fact that they do not fully understand the big picture of the technology they are writing about. The attempt to fully and explicitly state the meaning that was formerly only implied may well expose holes in the writer’s understanding that the writer was not aware of. (It is said with reason that you never really learn something until you try to teach it.)

And then again we have to ask, if the information is implied by the order of the document or the structure of the TOC, will the reviewers notice it, or notice flaws in it? (Personal experience tells me that the answer to that question is a definite No.

What do you think? What information is currently hiding in your TOC? Is it time to bring it out into the light and express it explicitly in a topic of its own?