Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 6,100+ subscribers. (See email archive here.)

Search results

Quick reference guides (Trends to follow or forget)

Trends to follow or forget

by Tom Johnson on Feb 27, 2022 •
categories: technical-writing

This post is part of a series that explores tech comm trends that I've either followed or forgotten, and why. The overall goal is to better understand the reasons that drive trend adoption or abandonment in my personal career. This post focuses on quick reference guides.

Quick reference guides

Quick reference guides refer to short 1-2 page guides, attractively formatted often in multi-column layouts, that get users going with succinct descriptions of the key tasks in a software application. The idea is that users almost universally resist slogging through a long user manual and instead prefer to get up and running quickly. They often need only minimal amounts of information to get started; the rest they might figure out on their own through trial and experimentation. These quick reference guides could be printed and distributed to users at conferences, during training, attached to newsletters, or delivered in other contexts. For more info, see my series on quick reference guides.

Why I embraced quick reference guides

Although we were primarily delivering documentation through online formats, we still wanted to give the user something to get started. At the time, the popularity of video further marginalized the role of text, especially long text-based manuals, and this quick reference format allowed us to reduce text but still provide instruction for users to get started. Most PMs loved the quick reference guides I created. One PM told me that he actually shed a tear the first time he saw the quick reference guide I delivered — he felt that tech writers finaly understood that no one wants to read long volumes of documentation.

Designing quick reference guides tapped into my creative side, and I found myself interested in layout and design, so much that I often browsed magazines to find layouts that I could steal for quick reference guides. I ramped up on InDesign and created half a dozen different standard templates for quick reference guides.

Why I abandoned quick reference guides

Quick reference guides were always considered icing on the cake — not part of the core deliverables, just something extra that we provided. As I moved into developer documentation, instead of providing these 1-2 page PDFs, I instead gravitated more towards getting started tutorials, which could be delivered online with the rest of docs, weren’t confined to a highly styled and formatted print layout, and could include more detail, especially code samples that wouldn’t normally fit within a print layout.

Sponsored content

Current status

Nearly every gadget I buy seems to come with a quick start guide, or some shorter 2-3 page setup guide rather than a long reference manual. Providing this shorter guide seems to be a common standard for many products. Within developer docs, the getting started tutorial is common, and it’s rarely something intended to be printed. Making information fit a print-based format often didn’t work well because most tech writers phased out of desktop publishing tools (e.g., InDesign), and wanted to put the content within the same web output as their other docs. When you put the quick reference guide online, it’s easy to simply link out to topics for more detail rather than trying to condense and summarize the information into a 1-2 page guide.

Takeaway

Quick reference guides help satisfy readers who resist longer documentation but still need help to get started. However, in developer documentation, getting started tutorials are more common and work better when integrated with the rest of the documentation; getting started tutorials also don’t have constraints about page space or layout.

Buy me a coffeeBuy me a coffee
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. 6,100+ subscribers. (See email archive here.)

follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer / API doc specialist based in the Seattle 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.

Comments