Quick Reference Guides: The Poetry of Technical Writing

How many times have you written a 75+ page guide and heard the customer say, This is great, but can you give us a condensed version?

After the third or fourth time I’d heard this, I decided to actually try it. I wasn’t sure exactly how to lay it out, so I spent a couple of days flipping through magazines — especially WIRED — looking for attractive layouts to copy.

I also needed a better tool than Word, and managed to acquire a copy of Adobe InDesign. After a few days of prototyping and writing, I finished my first one-page quick reference guide.

At the next project meeting, I brought color copies of this one-page version of instructions. The response was overwhelming. You’d think I was handing out free candy. Everyone wanted one.

They immediately started looking it over. In contrast to the pained expressions I’d seen after handing people long manuals, their faces showed incalculable glee. At that point, I knew the quick reference guide was a must-have deliverable for every one of my projects.

The names can vary — “Cheat Sheet,” “Getting Started,” “Fast Track,” “Job Aid” — but the concept is the same. Condense the most important information into one double-sided page. By “condense” I don’t mean shrink the font to 6 pt., decrease the leading, and eliminate all white space. With the quick reference guide, you take something that’s robust and complex, and distill it down to its essence, but distill it in a way that brings perfect clarity to users. Quick reference guides are like the poetry of technical writing.

Part of the appeal of quick reference guides is the close way they model software learning. Almost invariably, when people need to learn an application, they follow this same pattern:

  1. They sometimes read a little bit about the product (maybe 2-3 minutes).
  2. They open the product and see if it’s intuitive to figure out without the manual.
  3. When they get stuck, they turn to the help for information about a specific task.

The quick reference guide serves the user’s needs in step 1. Arguably, many people don’t even complete step 1, and just dive straight into the application. Still, having a one-page guide to quickly refer to while stumbling around the user interface for the first time can be helpful.

Other than brevity, how then are quick reference guides like poems? It’s more than just being concise. With poetry, the poet attempts to evoke a mood or paint a moment, and in that brief moment, capture the entire essence of something. Here’s an example of one of my favorite poems, “Lying in a Hammock at William Duffy’s Farm in Pine Island, Minnesota,” by James Wright.

Over my head, I see the bronze butterfly
Asleep on the black trunk,
Blowing like a leaf in green shadow.
Down the ravine behind the empty house,
The cowbells follow one another
Into the distances of the afternoon.
To my right,
In a field of sunlight between two pines,
The droppings of last year’s horses
Blaze up into golden stones.
I lean back, as the evening darkens and comes on.
A chicken hawk floats over, looking for home.
I have wasted my life.

In 13 lines, the poet has captured the entire essence of a lazy summer. The last line in particular, “I have wasted my life,” contains levels of depth.

Writing a quick reference guide is much the same effort. It’s not that you merely cut words to give a shorter manual, but that you try to compress the manual and express in its five-word equivalent.

I’ll grant that the task is probably impossible for technical material. Still, the attempt is there. The philosophy remains the same. Teach us how to use this manual in 5 minutes rather than 5 hours. It’s a philosophy of simplification and linguistic efficiency.

Many people think that the relationship between brevity and obscurity trends in the following direction.

In other words, as your writing becomes more brief, the level of obscurity increases. Actually, a good quick reference guide that does the job in a minimalistic way can have the opposite trend: becoming less obscure as the brevity increases.

This is because, simply put, no one reads the big manual. If you force the reader to wade through hours of preliminary text — a table of contents, table of figures, preliminary legal jargon, explanations of icons and style notations, introductory pages, lists of file menus, tab menus, icon meanings, and so on, before even getting to an actual task — the reader’s patience times out long before the manual ever teaches them something. I remember one time I was reading an AuthorIt manual. I’d reached page 87 and still didn’t see a single how-to task.

You don’t want to focus on too much in a quick reference guide. Remember, the poet focuses on a telling moment, and doesn’t narrate the whole of history. Likewise, the scope of a quick reference guide focuses on core tasks — tasks that are representative of the application as a whole.

Also, don’t be deceived by the brevity and scope of the quick reference guide. In wrangling with layout, scope, and concision, you might spend several days writing just one page. But when you’re done you can practically hang it on your cube wall.

A good layout tool is handy when creating quick reference guides. Adobe InDesign is a powerful tool, but you could probably make do with any program you’re familiar with. Here’s a sample quick reference guide template (an Indesign .indd file) that I sometimes start with, and then modify to best fit the help content.

If you have any sample quick reference guide layouts that you like, I’d love to hear about them.

Update: For more information on quick reference guides, see my list of other posts and templates on quick reference guides here.

follow us in feedly

Adobe RobohelpMadcap Flare

This entry was posted in general on by .

By Tom Johnson

I'm a technical writer working for a gamification company called Badgeville in the Silicon Valley area in California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), content development (DITA, testing), API documentation (code examples, programming), web publishing (web platforms, Web design) -- pretty much everything related to technical writing. If you're trying to keep up to date about the field of technical communication, subscribe to my blog either by RSS or by email. To learn more about me, see my About page. You can also contact me if you have questions.

31 thoughts on “Quick Reference Guides: The Poetry of Technical Writing

  1. Pingback: PoeWar.com Writer’s Resource Center

  2. Scott Skibell

    Tom,

    Great post. Job aids can bring significant value to an organization. I remember creating a color-coded series for our sales team that quickly summarized our various solutions. My reps loved them because they were succinct and referenced them back to where they could find more information. They were a great compliment to the online training.

    In addition, they weren’t written in “marketing speak.”

    I’ll be interested in hearing more on your experiences. Topics can include: tools, layouts, use of color, tables, charts, matrices, font combinations, and examples.

    Scott

  3. DP

    Loved the poem as illustration for the concept of brevity!

    My employer has hinted at wanting something just like this for quite a while now. We have tried different formats: Quick Reference Guides, Workflows, etc. Nothing has worked so far, because we are still trying to use old formats to do new things.

    I don’t know if I can get approval for a copy of InDesign or something like it, but it’s worth a shot. (Money at our company, as it is everywhere, is tight). I think if I can produce something like this for the bosses in a trial copy, I’ll find the expense approval will go smoothly.

    DP

  4. tr

    We use a few different quick ref cards for a few different products – and with printed manuals on the decline, its a nice and simple way to still have something to look at and get the user started in the right direction without opening anything but the dvd case. We’ve used a tri-fold 8×11 double-sided and most recently, a single fold 8×11 printed on glossy card stock that fits neatly into the dVD case. That quick ref covers all of the major tasks you can do with the app in a sequence that ends with an actual result. It wasn’t easy getting everything in and we had to cut a lot – that was a great task in itself, and let me see how easily bloat can make its way into sections that should be more task-oriented. Our templates are in Word and Frame.

  5. Craig

    I’d love to know how to create a Quick Reference Guide.

    This would make for an interesting project. The manuals I am revising and updating are around 200 pages. I know users and salespeople would like the Reader’s Digest version of these.

    How does one condense the equivalent of a dictionary into a “cheat sheet?”

    I’m wide open here. My tool of choice is MadCap Flare, if that helps.

  6. Pingback: MadCap Software • View topic - Creating a Quick Reference Guide

  7. Tom

    Craig, just pick out some of the most important tasks and describe them as briefly as possible. You may have to bend your style guide rules to do this (e.g., perhaps eliminate results statements, button or link descriptors, and introductory explanations).

    Re using Flare for the QRG layout, I think you’d have to be really good at CSS to make this work. Using columns and text boxes in Microsoft Word would probably be a lot easier.

  8. monkeyPi

    Nice work, Tom. QSGs are so well-received by users that I assume I need to create them unless the client specifically directs me not to (in fact, I include them in our online user assistance help as PDFs).

    I have personally found that my users REALLY appreciate having one entire side of the QSG be an “annotated screen cap” – where a large screen capture is printed w/ all the relevant pieces/parts annotated with arrows/callouts (e.g., “Blankety icon – launches visualization tool”).

    The other side typically has the most important procedures listed and grouped in blocks that are aligned aesthetically, typically the half-dozen most used. If you have any small item screencaps (like tool bars) you could paste them in w/ descriptions of each icon. Maybe a table could come in handy if you have unique tool specific syntax the user might need defined.

    I use InDesign primarily, built from content from other raster/vector sources. In fact, I found a handy way to get the screencap in, by using Captivate to handle the screencap creation and annotations and then porting the resultant graphic through Flash and into InDesign. Not cheap, but very effective (and I’ve done so many now that the effort has paid for itself).

    I really dig your poetry metaphor… a good QSG is definitely where science and art meet. It gives a great opportunity to let some well-pent-up creativity juices flow.

    A few other tips I’ve learned:

    Spend another few bucks to get it laminated. One group of users I provide QSGs to look forward to their “new placemats” every few months. :)

    If you make several different versions for the same users, make sure to use a nice large title, in the same place, so users can quickly flip to the one they want (I even use tool-specific color schemes).

    monkeyPis last blog post..How well do you know your fonts?

  9. Steve

    DP, if the budget isn’t there for Indesign, try Scribus (www.scribus.net). It’s a free, open-source page-layout program available for Mac, Linux, and Windows. Quick Reference Guides are one of its strong suits.

    1. Stuart Edeal

      Steve, do you know of any sites that have examples or templates for Scribus? I would like to try Scribus for making some training docs/QRGs, but would like to see some examples.

      thanks

  10. Craig

    Tom,

    Thanks for replying.

    I understanding the part about boiling down the most important parts and briefly describing them.

    Ours is a large proprietary applications, which would make this an intellectual challenge.

    The part that intimidates me is your saying I really have to know CSS, especially if I’m using Flare. Truthfully, I barely know my CSS from CSI.

    I’m using Flare but I don’t know CSS very well yet. Is there a good workaround or “cheat” for this?

  11. Amy Stewart

    Hi Tom,

    This is my first post on your site, and I’ve enjoyed reading your blog. (I’ve just started my own design blog and have been looking at your site for inspiration.) I use InDesign daily as a graphic designer, and would like to suggest that you also consider looking at its excellent XML integration features. I’ve designed InDesign templates for clients that pull in data from an XML file. You might be able to automate a lot of the layout work that way, and even build a web interface to create the XML automatically for you.

  12. Tom

    monkeyPI,

    Thanks for the tip about dedicating one side to an annotated graphic with callouts and captions and also laminating the guide. I think that’s excellent advice. Next time I do one, I think I’ll try that approach.

  13. Tom

    @Scott, good point about the color coding. That’s definitely a good technique. The other elements you mentioned would make for good posts in the future.

    @DP, if money is an issue for InDesign, you could try using whatever tool is available to you. Still, InDesign is pretty powerful (and there was a learning curve for me too).

    @tr, I liked your comment about the bloat that occurs with regular guides, and how quick reference guides help us remember how to get more quickly to the task.

    @Travis, let us know how it goes.

    @Steve, thanks for the recommendation on Scribus. I haven’t heard of it, but it’s nice to know the alternatives.

    @Amy, welcome to my blog and thanks for leaving a comment. Can you point me to any tutorials on using the XML feature of InDesign? I tried exporting an online help file into it’s “xml format” and pulling it into InDesign, but there was obviously a lot more to that process?

    Thanks everyone for your comments on this post. I really enjoyed reading them.

  14. Amy Stewart

    Tom, here’s a tutorial on using XML: http://www.xml.com/pub/a/2004/08/04/indesign.html

    It’s a matter of tagging all your text in the document so it can read in the XML. In the case of your example above, you’d put tags on each different text style– header, subhead, body, and you’d put tags on each image. Then you can export the InDesign XML to see the way it looks and the order of everything. From there, you would edit the text in the XML file. When you go back into InDesign, look in the links palette and you will see that it shows that the XML link has been modified. When you update that link, all your new content will pour in.

    It’s pretty particular about the order of everything. I’m happy to send you a sample file if you want, or you can read more on the Adobe website or their user forums. It can really save a lot of time in the long run.

  15. Brian

    Just thinking out loud here, but I wonder, is paper the right medium for these little manual McNuggets? I have a few such quick reference guides tacked to the walls of my cubicle but I only have so much wall space to accommodate this. You can only cover so much material in a quickie guide, and you only have room for a finite number of these.

    I’m not sure how this could be implemented practically, but couldn’t contextual help popups come to the rescue here? Dare I say, could it be time for the return of Clippy? Or perhaps a “Quick Reference” link at the top right-hand corner of every screen? Or maybe a tip of the day?

    My point being, how many quick reference guides can a user amass before they need a quick reference guide guide? Wouldn’t it be best if help came to the user and not vice versa?

    Maybe this is off topic but it’s the first thing that came to mind when I envisioned a laminated quickie card in my desk drawer.

    1. Caroline

      I may be a bit late to the party here, but I came across all this when looking for templates to base some concept reference sheets on. All these tips and such are wonderful! Thank you!

      I haven’t done much in the way of quick ref guides, I’ve always been handed legacy manuals and told to update them, or been told “we want a manual and nothing else”. Now that I’m in a doc role that lets me think about my deliverables as well as create them (what a concept!) I am chomping at the bit to do some innovating!

      To respond to the “paper necessary?” comment, in my experience with watching users use the tools I was writing about, sometimes they wanted online help, sometimes they wanted printed material. It really depends on the person and how they learn. So having laminated cards as well as context-sensitive help is likely a great solution to appeal to all people within the client base.

      Personally, mine are going to go on 8.5 x 11 double-sided sheets, laminated and ring clipped on a corner to hang above the workstation, with a link on the desktop to the PDFs if users are so inclined that way.

      Now, to get buy in…. *evil grin*

      1. Tom Johnson

        Caroline, thanks for leaving a comment about the quick reference guides post. I have a collection of quick reference layouts and other information here: quick reference guides. Your plan of one double-sided laminated sheet sounds great. One of the frustrations I’ve had with this format is that I spend so much time fiddling with design. But the end products are more appreciated than any manual I’ve produced.

  16. Bruce Curley

    Tom,

    I agree with you about the utility of quick start guides.

    For a medical device we developed, I just created an extensive hardware and software manual for the engineers and scientists, and quick start guide for everyone else.

    An old war story. Years ago, a company wrote the software for satellite phones (satphone). The satphone itself was manufactured in Germany…and the manual was in German. We got an emergency request for a quick manual…in English. This was in the days before software translators and it would have taken weeks to translate the 500 page manual. A couple of special forces guys in Granada needed to operate the satphone, but the manual was in German.

    I suggested we create a quick start guide with the setup, how to make a call, and how to complete a call covered, which is all they really needed. Everyone in the meeting looked at me like I had two heads. Fortunately, the leader of the project saw the utility and I got it done in 3 days.

    Some years later I actually met a guy who was part of that special forces group. It turns out that by the time he received the satphone instructions I wrote, they were on a laminated card the size of a card in a card deck. Small world, eh?

  17. Pingback: Why it can be good to spend days writing just one page « Orion Spur

  18. türkei urlaub

    very amazing info about complex writing. I am also a writer and share same difficulties with you. . Thanks for your diligently works. Plese give much more new content in order to follow up your nice blog.

  19. Pingback: Quick Reference Guides: Short and Sweet Technical Documentation | I'd Rather Be Writing - Tom Johnson

  20. Bob Winslow

    Great site, was hoping to get some help.
    Ive been asked to quote a price for taking an over 500 page manual and 300 page companion Book on the topic of elderly care, and making it accessible to administrators in a nursing home.
    The manual isnt only procedures, but contains principles on how to create an environment that will benefit those in your care.
    Im thinking a 10 to 20 page reference guide would do the trick.
    How do technical writers go about estimating how much to charge?

  21. Pingback: Quick Reference Guides The Poetry of Technical Writing I 39 d | Hammock Stand

  22. Pingback: This Week’s Top Ten Poetic Picks | TweetSpeak Poetry

Comments are closed.