Quick Reference Guide Q&A

Ben — Thu, 11 Feb 2010 12:00:24 +0000

Yesterday, I gave an STC Web seminar on using quick reference guides as part of a documentation set. (I’ve included a picture of how I used my wife’s earwarmer to work around the fact that the speakerphone feature on my new phones is less than desirable.) I answered a number of questions that participants typed into the meeting’s chat box and would like to pass them on. However, I ran into some technical difficulty when I tried to save the chat transcript, so I’m going from memory when writing these questions. These aren’t in any particular order other than the order in which I remembered them. I’ll also do my best to answer, especially now that I’m not on the spot.

What’s your favorite typeface for quick reference guides?

Given the audiences I write for, I anticipate that most of my guides are going to be printed, so I use a serif typeface for body text. I’ve gotten somewhat weary of Times New Roman—so little personality to go along with its readability—so I’ve gone to Cambria. (I know that Word 2007 has heading styles pre-programmed using Cambria, but I usually use sans serif typefaces for headings.) I think Cambria makes a good body typeface.

For headings, I may use Arial, Lucida Sans Unicode, or something similar. I don’t really care for Verdana because it’s so wide. And when you bold Verdana text, it blows up like a balloon.

How do you estimate how long it takes to create a quick reference guide?

That’s a tough question because it varies. How long a guide will take depends on how much of the content is text or images, how much of the content you can use from an existing help system, and so on. If you’re just starting to create quick reference guides, they may take you longer, but as you do more, you’ll probably get faster at them. But each one can take its own tender loving care, so it’s hard to say for sure.

What do you do when SMEs want a quick reference guide and it doesn’t really fit the situation?

One of the great things about quick reference guides is that after you’ve done a few, project managers, SMEs, and others become fans. Then they come up to you and say, “Hey, we need a quick reference guide for . . .”

This can also be bad—if they really don’t need one. And you have to tell them that.

I think the best thing here is to have the requestor explain the situation. Then talk through how the quick reference guide will or won’t meet the need. If there’s something better, like a video tutorial, explain why. It shows expertise when you can explain why a quick reference guide isn’t appropriate for a given situation rather than promoting it as a one-size-fits-all method of delivering documentation.

Do you put quick reference guides in the documentation plan or project plan, or do you just do them when the need comes up?

It depends. It’s best to try to anticipate the need for quick reference guides when a project is in its early stages. Then there’s a budget for the time you’ll need, and you can schedule that work.

However, as mentioned earlier, sometimes a need comes up unexpectedly. The project manager or a SME may see a need, or you may see it. If it’s a valid need, then some negotiation may be in order. Some of your work may have to be moved around. If the customer or manager wants a guide that wasn’t planned on and you anticipate that it will take more than a few hours, let them know that something else will have to slip.

I wish I could say that I’m a whiz at knowing at the beginning when a quick reference guide will be a great addition to my documentation set. But to this point, the need has usually made itself known while the project was in progress.

What typeface do you use if something will be viewed both online and in print?

The general rule is to use serif typefaces for body text that will be read in print, and sans serif for text read on the Web. (You’ll notice I’m breaking the latter rule on my site. But I made a deliberate choice to use Georgia.) If your guide is going to be read in both places, do some additional research if needed and find out which will be done more than the other. Follow the rule for whichever medium will be used more. However, if it’s pretty even, go with sans serif. I think a sans serif font is a little easier to read in print than a serif font is to read on a screen. But I don’t have any research at hand to back up that statement.

Do you coordinate with technical support when deciding what information is essential vs. nonessential?

To give a bit of background on this question, I explained in the presentation that when you’re creating content for a quick reference guide, it’s good to separate your information into essential vs. nonessential categories. That way, you include what’s essential, and if you have room left over, you can add some of the nonessential stuff. Further, if reviewers want you to add text to the essential concepts, you can bump some nonessential stuff out.

If you’re creating a guide for a product that hasn’t been released, then it doesn’t really make sense to contact support. At this point, like most pre-release documentation, the guide is anticipatory. We’re anticipating what users will need to know. However, if the product is has been released and you think a new guide would be beneficial, I think it would be helpful to get information from support on users’ questions or to find what knowledgebase articles are accessed most. This is probably a good practice for any technical communicator.

But no, personally, I haven’t engaged technical support while putting my guides together.

Do you include cross references among guides?

Not often, but every once in a while, if I have more than one guide for a product, each serving a different purpose, I may need to refer a reader from one to another. However, in one project, I included electronic versions of guides with the help system in the software build so that I could link to it from pages like the FAQ because it answers some of the questions. I don’t think there’s anything wrong with cross referencing among guides if it’s more appropriate than repeating a bunch of information in multiple places.

Could you include quick reference guides in a manual along with the chapters?

This is an interesting idea I hadn’t considered before. But if you’re creating a manual anyway, it could be a good idea to include a quick reference guide (or set of them) on a perforated sheet for easy removal—something showing the most important concepts from the section or the entire manual. It would take some coordination with the publisher so that you have perforated paper in the right places, but it’s an idea that has merit.

Bookmark It

Hide Sites

Gryphon Mountain Journals » quick start guides