Quick reference guides
- Quick reference guides
- Why I embraced quick reference guides
- Why I abandoned quick reference guides
- Current status
- Takeaway
- Next post
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.
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.
Next post
Continue to the next post in this series: WordPress and web CMSs.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.