Document 360: #1 Knowledge Base Software
Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,400+ subscribers

Search results

Document 360: #1 Knowledge Base Software

Single-page docs versus "Click Insanity"

by Tom Johnson on Jan 12, 2014 •
categories: api-docfindability

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.

Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,400+ subscribers

follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer based in the San Francisco Bay area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.