This guest post was written by Logan Mazza, a senior technical writer at Veeva Systems who is passionate about innovations in technical communication. Logan is certified both with MadCap Flare and Salesforce and is constantly looking for new and exciting ways to deliver documentation in ways that improve the reader's experience.
Quick reference guides are short, easy to read documents that distill complex instructions into simple, fundamental steps. These guides are a fantastic way to help your readers quickly perform specific tasks with your company’s product they may need to complete as part of their day, without needing to read a lengthy manual.
Technical communicators may need to create these guides on a recurring or one-time basis, depending on the industry, audience, and product. MadCap Flare, a leading technical documentation software, simplifies the creation of these guides with its powerful features for creating responsive, interactive content that can be easily updated and published across multiple formats.
Let’s explore who uses a quick reference guide and what key sections you should include to make your guide useful and effective.
Who Uses a Quick Reference Guide?
Understanding who a quick reference guide is for is the most important step of writing one. Identifying your audience should be the topmost priority and should inform every decision made during the writing, editing, and publishing process.
Here are some typical groups who use quick reference guides:
End Users - These are users who directly interact with your product, the people for whom the product was made. Whether it’s user manual software or hardware, these users are likely using a quick reference guide to obtain guidance on how to perform a specific task, potentially for the first time ever.
Support Teams - Customer service or technical support teams may use quick reference guides as part of troubleshooting difficulties encountered by end users. These teams are notable as, depending on the industry, they can be teams within your company or teams from a customer. In some cases, policy and procedure manuals may supplement these guides to provide a comprehensive framework for resolving issues.
Trainers and Educators - Quick reference guides can also be used as instructional material used by training or education teams. In this case, your guide could almost serve as a type of homework assignment, handed out to trainees as part of certification or onboarding.
The Reference Guide Essentials
Once you’ve identified your audience, the next step is to create an outline of your quick reference guide. Here are the key sections you should consider including:
Title and Introduction - The title should clearly state what the guide is for, and the introduction should provide a clear and concise overview of the tasks and processes the guide describes.
Components and Important Context - This section is your chance to give your readers important information about any terminology or context that is necessary to follow the guide.
The Instructions - This section is the core of your guide. An ordered list provides a way for your readers to follow along themselves. Each instruction should be as concise as possible while remaining accurate and complete. Screenshots or other visuals are an excellent way to reassure your users that they are performing the steps correctly!
Troubleshooting - Depending on the type of guide, it might be a good idea to discuss some frequently encountered errors or some other way for readers to troubleshoot their program or device. This can go a long way in reducing reader frustration!
Additional Resources - Quick reference guides are, by definition, not the whole picture. Your guide should provide ways for your readers to access your main documentation or other relevant resources. This can be as simple as a hyperlink or, if your quick reference guide is in print, a QR code, or link to official websites.
Feedback and Contact Information - Sometimes a quick reference guide isn’t perfect immediately. Giving your readers easy access to get in touch for assistance or provide feedback on their experience is a great way to both build trust with your readers, as well as improve the complex documentation.
Publishing Information - Including a publish date or version number in your guide can help ensure readers have the most recent version of the guide. This is especially useful if you’re regularly producing printed documentation.
Things to Remember When Creating a Quick Reference Guide
As you write your quick reference guide, keep the following points in mind to make sure your guide is as useful as it can be.
Understand Your Audience
Who are your readers? Why are they reading this? What do they already know going into this guide? These are all questions you should ask yourself constantly during the draft and review process. Your audience should dictate your vocabulary; even your sentence structure. It can impact format decisions, for example, when to use a bulleted list versus a table.
Concise, Scannable, and Complete
Remember, a quick reference guide needs to be just that, in both design layout and readability. Avoid technical jargon and lengthy documents and only include what is required to complete the specific task that the guide is for. Another thing to keep in mind is that, depending on your readers’ knowledge base, they may scan your guide if there is a specific piece of essential information you’re looking for. Descriptive section headings, screenshots, and text sparingly bolded can all help as readers’ eyes are naturally drawn to those elements.
Test Before Publishing
Once the guide is drafted, you should test the guide to ensure it’s accurate and complete. If you’re able, having a peer or coworker review the guide is even better. This helps you eliminate any potential typos or inaccuracies before your readers find it, avoiding frustration and improving the document’s quality.
Conclusion
Remember, the goal of a quick reference guide is to enable readers to quickly complete tasks in as few steps as possible. The clearer, simpler, and more concise you can make your guide, the more effective it will be. Your readers will appreciate how easy your quick reference guide makes using your company’s products, which also lets the product put its best foot forward!
