Adobe Experience manager

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

Stitcher radio

Search results

Adobe Experience manager

Single-page docs versus "Click Insanity"

Jan 12, 2014 • api-doc, findability

Check out this presentation by Brandon Philips at the 2013 Write the Docs conference. In the video, Philips argues for "single-page docs," which are entire help systems rendered on a single page. He says that for many technical information sets, like APIs, having all the functions, classes, etc. appear on the same page reduces "click insanity" and allows developers to more easily find what they're looking for.

See the full list of 2013 Write the Docs videos here.

Some poor documentation patterns ("anti-patterns") noted by Philips include Amazon Web Services and Django-fluent-contents.

In contrast, some single-page docs he feels provide easier navigation include the following:

Take a look at the navigation through some of those single-page docs.

Philips said he didn't find many tools for creating single-page docs, so he created his own, naming it "Fixie Docs" (after the single-gear, no freewheel bicycle). You can download a copy of Fixie docs here.

Some audience members raised a couple of objections. One person said their research into the single docs method wasn't favorable. The users were overwhelmed with too much information on the same page, so they abandoned their attempt to look through it.

Another person asked how you could re-use information when it's all on the same page. Philips noted that this technique is probably more appropriate for APIs and other developer material. It's not for content that needs to be re-used. API and SDK documentation typically have long lists of methods, classes, calls, functions, or other technical objects. It doesn't always make sense to put this content on separate pages, especially when each entry is pretty short and highly related to each other.

Consolidating the material on one page with a sidebar navigation that automatically highlights the sidebar title based on your location on the page is a novel approach -- not for every kind of documentation, for sure. But for the type of material Philips describes, it seems like a good fit.

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.