Quick Reference Guides: Short and Sweet Documentation

by Tom Johnson on Apr 10, 2009
categories: technical-writing • quick-reference-guides

This is the proceedings writeup that my colleague Ben Minson and I wrote to accompany our presentation on quick reference guides for the upcoming STC Summit in Atlanta. Be sure to check out the quick reference gallery mentioned near the end.

Tom's Perspective: The Need for Shorter Documentation

Several years ago, the customers I wrote software manuals for kept coming to me with the same request. After giving them a 75-page manual or larger, the project managers, business analysts, or other customers would ask if I had a shorter version.

"Do you have a two-page version?" some would ask.

"Is there a condensed version?"

"We want the documentation to be, at maximum, no more than five pages," others would say.

I struggled with these requests, because I had no way to fit the content of my 75-page manual into one or two pages. It seemed absurd. But after a continual pattern of requests for shorter documentation, I had to do something.

Without a design background, I resorted to magazines for a layout that might be suitable for condensed help content. After finding a design I felt might work (it had four columns in the middle, sandwiched by a top and bottom section), I opened Adobe InDesign and started to duplicate the magazine layout.

It took me nearly a week, in part because I was learning InDesign and had to rewrite the help material in a compressed way, but when I finished and brought the one-page quick reference guide to the next project meeting, distributing a copy to each project member sitting at the table, their reactions surprised me.

As I handed the one-pagers out to the team members, they immediately started to read them. (Previously, when I handed out manuals, people only hefted them in hand, as if trying to guess their weight, or they looked immediately at the page count and sighed.) But with these lightweight quick reference guides, people read them immediately, and not only that, they liked them. They seemed to smile, with a sense of glee, as if having gotten out of some detention. What! Were these users happy?

The "almighty thud," as Martin Fowler describes it, and the subsequent disheartened gloom that usually accompanies the inch-and-a-half thick manual, was completely gone, replaced with a rejuvenated spring-like feeling in the room.

After this first response with quick reference guides, I decided to make quick reference guides a regular help deliverable with almost all my projects.

In this article, my colleague and I provide strategies, tips, and approaches we've learned in creating quick reference guides for software documentation projects.

When to Use Quick Reference Guides

When you begin any project, consider whether your users would benefit from a quick reference guide. The following are a few situations where quick reference guides are ideal:

One-time setup. If the product requires a one-time setup process and will work continuously afterwards, a quick-start guide can provide the user with the basics to get up and running. You may want a second document for more detail or troubleshooting, but a quick start guide can satisfy the needs of both advanced users and those who don't care about the details.

Limited functionality. A product with a small set of tasks may not need much documentation. If you can sacrifice only a little information to fit most of the documentation on the front and back of a single sheet of paper, you can format it as a quick reference guide rather than creating a booklet or manual.

Core tasks. If the uses of the product are varied but several core tasks are performed most often, a quick reference guide can provide the basic steps for those tasks, while the rest are described in a separate document. Depending on the length or complexity of the core tasks, you may be able to fit three to six tasks on each side of the quick reference guide. This allows users to accomplish the bulk of their work without having to search through a help system or manual.

User roles. Software may be role-based in an organization or process. Taken as a group, the roles may perform more than half-a-dozen tasks considered to be essential or common. But how many core tasks are there per role? If the answer is six or fewer, consider a quick reference guide for each role.

Transition from legacy systems. When a new (especially complex) product replaces an old one, the customer may invest in a transition period that involves some bridging of interfaces or processes. You may need to produce some documentation that eases the transition but will no longer be needed once this period is over. A quick reference guide can satisfy the need while allowing you to focus on the documentation that will ship with the final product.

Large documentation set. If you're creating dozens or hundreds of topics in a help system or pages in a manual, consider the resistance users may feel to diving into that much material. Decide whether there is a set of information most important for users to know going forward.

Busy users. If your users are busy people who barely have time to reply to an email message you send, much less read long documentation, consider giving them a quick reference guide instead, since it's probably the only material they will actually read. The quick reference guide is usually a format that fits them perfectly.

Developing and Selecting the Content

One of the most challenging aspects of creating a quick reference guide is deciding what to include. If your quick reference guide is part of a larger documentation set, produce as much of the other documentation as possible first. This helps you to become familiar with the product and gives you the perspective to decide what is most important for the user to know to move forward. You will also be able to leverage existing content (to some extent).

As you produce the guide's content, divide it into two categories: (1) essential tasks and information and (2) important but non-essential tasks and information.

Don't be afraid to write more than you think you'll be able to use. As you design the guide, you may find you have extra room for some of the non-essential information. Or you may have to decide what to leave out once you've used up the available space in the document.

Designing the Layout

Not all information and tasks will fit in the same design. So although having quick reference guide templates can be helpful as you create the guides, rarely do the templates remain static molds that you can simply pour new content into.

For example, some help material may need four columns, others two, others may need a full-blown image, and some may have long, complicated tasks. You may need a large visual with steps in callouts. Other help content may call for lists of steps without the need for screenshots. Or you may not need steps at all, but rather conceptual reference information and workflow diagrams.

Because of the variety of help material, the layout and design of the quick reference guide needs to be flexible with the content. In some situations, the design must be created around the content.

Learning Design

In learning principles of design, one of the most helpful books is The Non-Designer's Design Book: Design and Typographic Principles for the Visual Novice by Robin Williams. Williams outlines four main principles of design: contrast, repetition, alignment, and proximity. These principles fit into a neat acronym: CRAP.

As we have played around with various layouts, we've tried to implement contrast, repetition, alignment, and proximity into our designs—sometimes consciously, sometimes not so much. Some guides exemplify the principles more than others. To see about 15 sample quick reference guide layouts, go to https://idratherbewriting.com/quickreferenceguides.

The following sections briefly summarize each of the four design principles Williams details in her book.

Contrast. Contrast helps establish hierarchical relationships among information. For example, adding contrast between headings and text helps the user better understand how the various sections of your document fit together.

Williams explains that most designers don't employ enough contrast. For example, if the only contrast between your headings and text involves making the headings bold or full caps, you might turn the contrast up a notch, incorporating color, selecting a different font (one that contrasts with the paragraph text), and making the font a larger size.

Contrast also draws the eye. If you squint at a page, or take note of where your eyes naturally focus, you'll see what a key role contrast plays. This is why headers sometimes have a strong background color with light text—because that contrast tends to pull your focus to it. Additionally, strong color at the bottom of a document can act as a visual anchor.

Repetition. Repeating a consistent design throughout the document can give integrity to the whole. For example, column and heading consistency can help unify a design. But more explicitly, if you have a small logo or other shape that you can repeat, this helps strengthen the coherence of the whole and reinforces unity of design. Repetition of color headings with bullet colors and note or tip styles can also establish a repeating design that unifies the document in a visually appealing way.

Alignment. Alignment is most apparent when something is out of place. Symmetry with paragraph blocks, images, headings, and other elements can make your eyes feel at peace. Alignment is more than symmetry, though. Your content can be aligned along a strong right or left edge. This alignment can strengthen and sharpen your design.

Text should rarely be centered, Williams writes, because centered text lacks alignment along a specific edge. As with the other principles, alignment of content in your design establishes relationships with other content. Alignment lets the reader know about the connection and relationship of the different units of content in your document. For example, if you are careless about the left alignment of a numbered list, readers will quickly see the content as messy and may wonder if the list is one conceptual unit or multiple units.

Proximity. Proximity refers to the grouping of like objects near each other. If objects don't have any relationship with each other, they shouldn't appear close together. In a quick reference guide, you may want to group important tasks in the main column, while keeping subordinate, less important tasks in a side column. The visual grouping lets users know, without even reading the text, that the location of the content has a relationship with the meaning of the content.

Starting with Magazine Layouts

Being aware of some design principles is handy, but it probably won't make you a master information designer. To compensate, you can rely on layouts from magazines as starting points. Visit a thrift store and buy a stack of magazines. Flip through the pages, looking for layouts that might work well with help content. Note the contrasts, repetitions, alignments, and proximities of the text and images.

As you look at magazines, you'll notice they all have at least one thing in common: compelling images. Almost no good magazine layout consists only of text. Balancing text with a graphic or two can make your entire design come alive.

Ideally, when you start brainstorming your design, choose a visual that reinforces the meaning you're trying to convey, such as a diagram or illustration. Even if the visual is only a screenshot of your application's home page, the screenshot will add balance and color to what would otherwise be a boring text document. However, because a quick reference guide offers limited space to convey information, be sure that your images communicate to the reader and don't just take up space.

Finally, remember that in order for a quick reference guide to be quick, you can't overload the document with too much content. Be selective and accept that you can't include it all. Sure, you could decrease the white space, the leading and kerning, the font size, the margins, and so on. In fact, you probably could fit the 75-page manual on two pages, but it will be unusable. Most appealing magazine layouts have limited text, often no more than several hundred words per page.

Tools

A number of tools are available for producing quick reference guides. Our experience has been primarily with Adobe InDesign. Tools we haven't used much but which may work for quick reference guides are Adobe FrameMaker, Microsoft Word, Microsoft Visio, Quark xPress, and Microsoft Publisher.

You may be comfortable with these other tools, but if you plan to create a lot of quick reference guides, think seriously about investing some time and money in InDesign.

InDesign offers the following strengths:

• Precise control over location of content
• Story flow between text frames
• Control over color, strokes, widths
• Object styles
• Linked images
• Graphics capabilities

If you include a lot of illustrations and images, you can embed Photoshop and Illustrator files directly into InDesign files, without converting them to JPG or GIF formats. And you can edit the images as needed without having to reinsert them.

However, InDesign is a complex tool, so it can take a while to learn what you need to know to use it effectively. It is also costlier than other tools, and the INDD format is not compatible with other software. This file format is also not backwards compatible from version CS4 to CS3.

Challenges

The benefits of the quick reference format outweigh the costs, but every coin does come with two sides. Be prepared to overcome the following challenges when creating quick reference guides:

Time and associated cost to create. Even though the quick reference guide is just one or two pages, it can take a week to write. Unlike an online help file, where space is practically unlimited, with quick reference guides you have to write for a specific information space, making decisions about what to include, how to include it in a minimalistic way, and how to lay out the information in an attractive design.

Limited reuse of content. To compress the help content, you may abbreviate sentences and condense your content to make it fit (for example, you might remove descriptors such as "button" or "link"). This condensed content usually can't be single-sourced with your other help content. Even if it could, the advanced layout in InDesign would make the single sourcing of your quick reference content difficult.

Learning curve. If you've never used an advanced page layout tool before, get ready to dive in to the help and spend a lot of time figuring things out. (Of course that comes with the technical writing territory, right?) Try learning a little bit each day over a long stretch of time. You may find the InDesign Secrets podcast (indesignsecrets.com) helpful.

Accommodating requests to add more. Just when you've finished modifying the text to fit perfectly in the spaces of your attractively designed guide, having come up with brilliantly reworded sentences and shorter titles, a reviewer will ask you to add another section, or remove what you've already included. Making this revision usually complicates your design, causing you to shift around columns or eliminate other material. Sometimes revisions require you to change your actual design.

Localization. Realize that if you need to distribute your guides in multiple languages, the text that fit so well in the original language may break your design in the localized versions. You may have to spend some extra time massaging each version.

Benefits

In spite of the challenges, quick reference guides have a host of benefits:

Communication of simplicity. Users greeted with one page instruction sheets rather than 200-page reference manuals feel that, since you can fit the instruction on one page, the system must be easy to use. Whether this is true or not depends on a lot of factors, but the overall impression of simplicity is epitomized in the quick reference guide. It's an impression that project managers love.

Opportunity to develop your design skills. Creating a quick reference guide injects a little variety into what may be a dry day of procedural writing. You're not only creating information, you're designing that information. If you enjoy design, you'll find that creating these guides is highly rewarding. Additionally, your customers and other project members will recognize that your quick reference guides, though largely text, aren't something they could create themselves. Quick reference guides also showcase your audience and situation assessment skills.

Perfect solution for handouts. With each training or product demo, program managers or other facilitators usually like to give users something to take home. Quick reference guides work perfectly for this. The one-page distribution will significantly reduce costs as well. You can even laminate the quick reference guides, or get creative and convert them into placemats, office posters, or mouse pads.

Material read and reviewed. Unlike the 200-page manual that users dread and that reviewers never seem to get to, almost everyone can make their way through a quick reference guide. It is a consumable, manageable amount of information. Knowing you're creating something that people will both read and review improves your writing morale considerably.

Documentation usability. From a documentation usability point of view, quick reference material matches how people use products. Almost no one reads the entire manual before using a product, but they will often briefly glance at short instructions on one sheet of paper for ten seconds. The short version can get them pointed in the right direction.

Conclusion

As word gets out about the quick reference guides you create, you may start receiving an increased number of requests for one-page documentation from project managers who never considered your services a possibility before. Quick reference guides will open a window into new areas of your company and give your team increased exposure and recognition. Because of their high use rate, quick reference guides will also be one of the most rewarding deliverables you produce.

As you develop your quick reference guides, save your templates. If you would like to contribute them to the ongoing collection at https://idratherbewriting.com/quickreferenceguides for the benefit of others, send them to [email protected].

Recommended Reading

Fowler, Martin. "The Almighty Thud." Distributed Computing. November/December 1997. http://www.martinfowler.com/distributedComputing/thud.html

Johnson, Tom. "Lessons Learned with Quick Reference Guides: Timing and Truth." Feb 26, 2009. https://idratherbewriting.com/2009/02/26/lessons-learned-with-quick-reference-guides-timing-and-information-flux/

—. "Quick Reference Guide Formats: Tips for Finding Attractive Layouts." Dec 31, 2008. https://idratherbewriting.com/2008/12/31/quick-reference-guide-formats-tips-for-finding-attractive-layouts/

—. "Quick Reference Guides: The Poetry of Technical Writing." July 6, 2008. https://idratherbewriting.com/2008/07/06/quick-reference-guides-the-poetry-of-technical-writing/

Minson, Ben. "Quick-Start Guides Require a Minimalist Mindset." October 2, 2008

http://www.gryphonmountain.net/archives/techcomm/quick-start-guides-require-a-minimalist-mindset

—. "Try a Quick Reference Guide for Short-Term Documentation Needs." January 30, 2009. http://www.gryphonmountain.net/archives/techcomm/try-a-quick-reference-guide-for-short-term-documentation-needs

Williams, Robin. The Non-Designer's Design Book: Design and Typographic Principles for the Visual Novice. 1994. (Amazon link)

Next: 1.5 Documentation Usability: A Few Things I've Learned from Watching Users