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

Stitcher radio

Search results

Upcoming event:
I'm giving an API documentation workshop in San Francisco, California, on November 19, 2019. Check it out on EventBrite and register today to receive a $100 early bird discount.

Single-page docs versus "Click Insanity"

by Tom Johnson on Jan 12, 2014 • 0 Comments
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.

follow us in feedly