Adobe Experience manager

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

Stitcher radio

Search results

Adobe Experience manager

Reinventing the table of contents

Jan 26, 2015 • jekyll

I've been exploring different ways to create a table of contents (TOC). Traditionally, user guides have a long TOC in the left column of each page. This works all right when you have about 50 pages, but when you scale up the doc set to 500 pages, the TOC becomes a bulky, unusable mess.

For an example of the mess I'm talking about, see this TOC in Salesforce's documentation. An all-encompassing TOC model like this essentially repeats the initial Yahoo directory of the web, when Yahoo tried to provide an organized hierarchical table of contents for everything. Why present so many TOC options that aren't remotely related to what I'm currently viewing?

A better model for a TOC is to show only links relevant to a narrowed scope. (I explored some of these ideas in an earlier post here.)

Take a look at my evolving Jekyll prototype. The homepage has various panels (like Pinterest) that you can dynamically filter.

Jekyll homepage

When you jump into a page (such as Syntax highlighting), a mini-TOC appears on the left (if the page has subheadings).


To go back to the main panel page, go to the homepage (by clicking the product title in the upper left, "Jekyll notes"). This kind of scope filtering seems more practical for scaling doc sets.

BTW, the shuffling feature on the homepage is through a JavaScript library called Shuffle.js.

(Also, much of the content on this prototype is a mix of filler content + informal notes, so don't pay attention to it.)

What do you think? Does this model reinvent the TOC in a better way?

follow us in feedly

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in simplifying complexity, API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.