Starting Points with Quick Reference Guides: Gathering Before Designing

In The Back of the Napkin, Dan Roam explains that drawing pictures can help you solve problems. He says the first rule is to “collect everything possible up front” (p.58). After collecting all your information, you then “lay it all out where you can look at it” (p. 61). By laying out all the information, you can grasp the whole of it, make connections between various parts, see the important sections, and recognize patterns.

These two rules define the starting points when creating quick reference guides. Neglect them and you run into trouble.

For example, on a recent project, I sized up the application and decided the help content would be minimal. I could fit it all on a few one-page quick reference guides spread across several roles. I didn’t even need an online help, I decided, but would author directly in my quick reference guide layouts.

I opened Adobe InDesign, created a new document, and started writing the content directly in it. It began well enough, but little by little, the application started to reveal its complexity. Edge cases, special workflows, notes and other important information began to accumulate. I manipulated the text frames and column layouts to fit the information. Needing more space, I adjusted the line spacing, the font size. Then I removed a screenshot, and another. I increased the length of the columns, and so on, trying to make it fit on one page. After some deliberation, I decided to cut entire sections that weren’t actually necessary. So I then added a screenshot back in.

The information continued to fluctuate. After some time, having modified the design several times to accommodate the content, I realized my error: I was starting at the end rather than the beginning. I needed to see all the information at a glance before designing the quick reference guide. Without a complete picture of the documentation, I couldn’t see which tasks were essential, what to include and exclude in the guide, or how it should be arranged. It became an exercise in frustration.

Trying to author within a design is an exercise in frustration

Trying to author your original content while worrying about design is an exercise in frustration

Returning to Roam’s point: First gather all the information. Second, lay it out on the table to see. Roam actually calls this second principle the Garage-Sale principle, because once you lay out all the information in front of you, you can then begin to see it with more clarity. You can note patterns and spot duplicate and overlapping content. You can start organizing it, throwing away extraneous information, noting gaps, and so on.

By gathering all information first, you can recognize patterns and see how it fits together

By gathering all information first, you can recognize patterns and see how it fits together

The next time I needed to make a quick reference guide, I didn’t even start to think about the design. Instead, I followed Roam’s advice. I opened up a help authoring tool and wrote out the procedures in full, without considering limitations of space or design.

After collecting the information, I reviewed it with a subject matter expert to make sure the information was accurate. She noted some steps that were wrong, information that was missing, and brought up some key issues users would face. I made the revisions to my help content.

I then asked a colleague if I could watch her follow my instructions. I scheduled an hour of her time and then just observed her casually as she tried to perform the instructions. It blew my mind that she could not complete even the first step. From the start, the plugin she needed to download ended up breaking the application she needed to test. When we tried the web interface workaround, she noted serious usability issues with a few fields and a bug with the lookup selector. I made notes about what I needed to fix in my documentation and made the adjustments.

After I felt I had a fairly complete and accurate body of documentation, I arranged the files in an online table of contents. Because it was relatively short (eight pages), I also printed the pages out and physically laid them side-by-side on my desk. Looking at all the information, I realized two procedures overlapped each other. They seemed too redundant to be separate, so I combined them into one task with a note. I also realized another process needed separating out, so I created a new task for it.

Had I been working with this information in little text frames in Adobe InDesign, adjusting and modifying the sentences each time to accommodate new or fluctuating information within the confines of a tight design, it would have driven me crazy. It would have taken a lot of time, hours spent worrying more about how the content affected the design rather than the content itself.

Adobe RobohelpMadcap Flare

This entry was posted in quick reference guides on by .

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), API documentation (code examples, programming), and web publishing (web platforms, interactivity) -- 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, email, or another method. To learn more about me, see my About page. You can also contact me if you have questions.

6 thoughts on “Starting Points with Quick Reference Guides: Gathering Before Designing

  1. ivan walsh

    First!

    Hi Tom,

    There’s alot of good sense in here. I’ve always found the sketching things out helps, especially when you want to get the bigger picture or when doing process design work.

    Also, when interviewing programmers, I often ask them to draw me a diagram when they get stuck or when we get bogged down.

    Having pictures at hand helps kick-start the overall discovery process.

    Enjoy Vienna when you get there. Great place.

    Ivan

    1. Tom

      Hi Ivan, thanks for the comment, and sorry for my slow reply. Asking programmers to draw diagrams of what they’re explaining is a great tip. I’ll keep that in mind the next time the discussion goes over my head.

      Sounds like you’ve been to Vienna. Do you recommend any essential sites to see?

  2. Eddie Gear

    Hi there,

    This is a very informative post. I’ve been looking for information on this topic for a while. As I technical writer I always found this a bit of a confusing process :). Thanks for sharing your knowledge and shedding some light on the topic.

    Cheers,
    Eddie Gear

    1. Tom

      Hi Eddie,

      Thanks for adding your feedback about the post. I’ve found that following this process does make the whole process of creating quick reference guides a lot less frustrating. Do you create a lot of these types of documents at your work?

  3. Ivan Walsh

    Hi Tom,

    The The Vienna State Opera (Wiener Staatsoper) is an opera house is a must. This is where Beethoven, Mozart and others all played. Was v lucky to get tickets here about 15 years ago where Carreras was singing La Boheme. Real old world.

    http://en.wikipedia.org/wiki/Vienna_State_Opera

    The other is Kunsthistorisches Museum

    http://en.wikipedia.org/wiki/Kunsthistorisches_Museum

    The Gustav Klimt paintings are stunning. Just for these I’d go.

    By the way, if you have time, you can get the train down to Venice. It goes over the mountains.

    Only Highway 101 outside SFO is more scenic, imho.

    Enjoy the trip.

    Ivan

    PS – lovely chocolate shops there. REAL chocolate!

  4. Shelley

    Tom,

    I found this information to be extremely useful and true! I often get so excited about the document design, that I don’t finish the content first, and end of creating a lot more work for myself. Point well taken.

Comments are closed.