Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,220

Adobe Robohelp

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.

http://www.youtube.com/watch?v=rXcdTYuxwys

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.


Get new posts delivered straight to your inbox.

Subscriber count: 3,220

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.