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?

Flow Chart

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?

, , , ,

8 Responses to What’s Hiding in Your TOC?

  1. Jeff Coatsworth 2012/06/12 at 14:44 #

    I agree Mark – overviews are definitely needed. In my experience, they’re the “executive level” summary that everybody wants to get of each software module – what’s this module do? Will it work for what I want it to do? etc.

    I use workflow topics to help order my writing – if I can’t figure out what has to happen in what order, then how is the client going to? Once I’ve got the skeleton of the workflow done, then I can proceed to knock off each of the steps as a separate topic – a little cross-referencing, and I’m done ;>)

    • Mark Baker 2012/06/29 at 11:42 #

      Hi Jeff, thanks for the comment. I too believe that workflow topics are essential, both to the reader’s experience, and to the writers ability to discover what tasks really need to be documented.

  2. Debbie M. 2012/06/12 at 15:45 #

    What a wonderfully potent page that TOC is! It contains workflow, overview, and context (how does where I am fit into the big picture?).

    • Mark Baker 2012/06/29 at 11:45 #

      Hi Debbie. Thanks for the comment. A TOC would be potent indeed if it could actually express all those things adequately!

  3. Jørn A Hansen 2012/06/14 at 12:20 #

    Yes, so would a TOC with comments ? Or even an illustrated TOC be even more potent – and what are easy ways to create and maintain it when you want output in different formats like the printed/folded cardboard reference card, the online pages and the presentation sans death-by-PowerPoint for introducing ‘stuff’ to users?

    • Mark Baker 2012/06/29 at 11:48 #

      Hi Jørn. Thanks for the comment. I think what this reflection points to is that a richly liked topic is acts like an illustrated/commented TOC for topics on related subjects. This, I think, is part of what it means to create Every Page is Page One topics: one of the functions they perform is the function of a TOC.

  4. Vinish 2012/06/25 at 13:46 #

    Many help manuals explain *how* to use a feature or do a task, without explaining *why*.

    I use a full-workflow diagram for whole system, and then subsets of this main flow diagram at the beginning of each chapter or procedure to ensure that user understands how that particular procedure fits into the big picture. I do not think I can cover this aspect in the TOC, explicitely.

    • Mark Baker 2012/06/29 at 13:18 #

      Thanks for the comment, Vinish. This sounds to me like a great approach, at least for a system that has a single dominant workflow. I like the idea of the full workflow diagram and then the parts of the diagram being used to head individual topics. That would seem to do a good job both of providing a quick overview of the subject and helping to quickly orient the reader to where they are in the system.