During the meeting, as the team looked at the callouts on the quick reference guides, they felt there was too much text. Reduce the text, increase the font, they said.

Reduce the text? Make it even shorter? The content was already a two-page quick reference guide. Were we now to make it a postcard?

I get this feedback a lot. Hand any help material to a non-writer in a meeting, and the request I routinely hear is to make it shorter. Too much text. People aren’t going to read this, they say, as if they were expecting to take in the entire content with a five-second glance.

My experiences lead me to wonder about the possible transformation of reading experiences, and if reading is still the same in our online age. When you add in the immediacy of online content, hyperlinks, mobile formats, RSS feeds, and endless information, do people still read in the same way? And if people read differently today than they did 50 years ago, how do we change our help deliverables to fit contemporary reading patterns?

Attention Spans

Probably the most radical argument about shifted reading behaviors comes from Nicholas Carr, who asserts that Google has rewired his brain, reduced his attention span, and given him more superficial reading habits, including some fidgeting. In short, Carr thinks that Internet content has made him “stupid.” In an article in The Atlantic, Carr explains,

Over the past few years I’ve had an uncomfortable sense that someone, or something, has been tinkering with my brain, remapping the neural circuitry, reprogramming the memory. My mind isn’t going—so far as I can tell—but it’s changing. I’m not thinking the way I used to think. I can feel it most strongly when I’m reading. Immersing myself in a book or a lengthy article used to be easy. My mind would get caught up in the narrative or the turns of the argument, and I’d spend hours strolling through long stretches of prose. That’s rarely the case anymore. Now my concentration often starts to drift after two or three pages. I get fidgety, lose the thread, and begin looking for something else to do. I feel as if I’m always dragging my wayward brain back to the text. The deep reading that used to come naturally has become a struggle. (Is Google Making Us Stupid?)

In other words, rather than sitting down with a book and immersing himself in it, drowning out the world around him as he drinks in page after page, he now gets restless after a few pages. His attention span compels him to turn somewhere else, to read from a different author or source. His reading experience is much more cursory and shallow, thanks to the Internet.

Steven Johnson also argues a similar point in the Wall Street Journal. He has the epiphany while sitting alone in a restaurant in Texas. He argues that the deep, immersive reading experience evaporates with the ability to immediately view or download any content, almost anywhere. Johnson writes,

Because [print books] have been largely walled off from the world of hypertext, print books have remained a kind of game preserve for the endangered species of linear, deep-focus reading. Online, you can click happily from blog post to email thread to online New Yorker article — sampling, commenting and forwarding as you go. But when you sit down with an old-fashioned book in your hand, the medium works naturally against such distractions; it compels you to follow the thread, to stay engaged with a single narrative or argument. (How the e-Book Will Change the Way We Read and Write.)

In other words, the shift from print books to online content, in which every page is linked to another page, in a giant web of connected content, has given readers a lack of patience. They can’t remain on one narrative thread for long periods of time. They instead jump around. They sample and move on, they glance and click. No one sits down to eat a long literary dinner any more.

Hyperlinks

One main enabler of the short, cursory attention span is the hyperlink. At the last STC Summit, Ginny Redish and Kathyrn Summers noted how the hyperlink becomes an obstacle for low-literacy users, causing them to click links randomly and lose their train of thought. Each hyperlink presents a forking path for the reader, presenting the reader with the decision to click elsewhere. If a reader is slightly bored, the temptation to move on to greener web pastures is often too much, regardless of the literacy level.

Smart Phones

Smart phones also contribute to the shift in reading behaviors. The smaller display and screen real estate on a smart phone, as well as the smaller font of the text, strain reading. But the portability of the smart phone compensates for the strain in an overpowering way, so that the reverse is also true: people read more, at least according to Peter Collingridge, a publisher of Enhanced Editions software for the iPhone.

Collingridge says that “People aren’t reading less on mobile devices, they’re reading more.” This is because “occasional reading suddenly became so much easier: on the bus, waiting for the tube, opening an app that remembers the exact place you left it for a quick literary fix becomes second nature very quickly.”

Collingridge finds that to deal with his insomnia, he’ll read his “iPhone in bed at all hours, without the need for a light” (Reading Wolf Hall on the iPhone).

Collinridge specializes in digital editions for e-books, so perhaps readers are able to enter the deep-focused reading state that Johnson describes, even on mobile. However, on my smart phone, a Palm Pre, I tend to only read RSS feeds. I can move through dozens of feed items relatively quickly, choosing to save good reads through my Read It Later app, which saves posts to Instapaper.

Reading an article longer than 3,000 words gets tiring, and I quickly feel like I’m making my way through Moby Dick. It’s a bit harder to jump and skim on the mobile device, because I can only see a two-inch span of the article. Still, I may read more content because I can curl up in my favorite position on the couch or bed and read from a device in my hand. I may lie there reading for an hour or more, but moving from feed to feed, from site to site, often in the dark.

This behavior no doubt turns habitual. Soon my reading pattern is to jump and click, moving from site to site, regardless of whether I’m at a desktop, a laptop, or holding a book or magazine. The smart phone inculcates a new reading pattern in me that favors short text.

As the following image shows, the shift in media from books to television, and then to video games, Internet, social media, and smart phones, has slowly rewired our brains. We have shorter attention spans. We prefer short texts.

Rewiring the brain through shifts in technology

Given this rewiring, perhaps we technical writers should start producing help materials optimized for this type of brain? I’ll come back to this idea in a minute. First, a few more arguments about how reading is transformed.

The Blog

In contrast to book authors, the army of daily bloggers cranks out a million short posts a day. One rarely finds a 5,000 word essay to slog through on a blog. And if you do find one, given the average literary skill online, it might not be worth reading carefully. In fact, most blog posts are re-spun cliches or ideas that we’ve already read or already understand, so skimming this content only makes sense.

Regardless of the content quality, if blogs are the new format for online content, and most are short articles (under 2,000 words), doesn’t this new standard for brevity reduce the reader’s ability to endure long, book-length texts? The more you read blog posts, the more you expect content to be short. We’re surrounded by a culture of content in which short formats are the norm.

Even critics who defend the intellectual depth of these short formats still acknowledge their brevity. Clive Thompson in Wired says, “The torrent of short-form thinking is actually a catalyst for more long-form meditation” (“The Short and the Long of It,” January 2011). His assertion is brilliantly illustrated through this simple concept diagram.

"The torrent of short-form thinking is actually a catalyst for more long-form meditation." -- Clive Thompson

Whether all of these short-form texts aggregate into long-form trends and deeper, more extensive analysis overall is beside my point. I cite Clive here as yet another critic who acknowledges the shift in formats from “long, well-thought-out arguments” to “text messages, tweets, and status updates.” These short formats may be micro-components of a collectively intelligent macro discussion. But the mere fact that discussions take place in short formats rather than long ones reinforces the trend I’m highlighting: short texts surround us as the norm.

Tags and Categories

In addition to favoring short forms of content, blogs are also structured with tags and category links, which invite readers to explore content thematically rather than as a whole.  Interested in the topic of web design? Click this web design category link and peruse the available articles. Or click the usability tag and see even more specific selections on the topic. Thematic reading often spans numerous articles rather than pointing readers to a single lengthy work. You end up reading an online bibliography or collection rather than a single book.

At my work, we just released a notebook tool that allows users to highlight passages and bookmark articles as they read site content. They can add the content to a folder and tag it. The result is a chopped up bag of short content that provides a litany of quotations, highlights, and article titles on a topic. All short and concise. A reader can move through dozens of sources, sampling each article in very little time. Eventually you’ll be able to share your collections with other readers, so readers will no longer be turning to lengthy primary source material for learning. Instead, they’ll move through a smattering of individual paragraphs from dozens of sources, all compiled together in a list showing 10 items per page.

So Much Content

Never mind the type or format of content, another cause behind the changed reading behavior is the abundance of content. With a thousand new posts in Google Reader all the time, access to every online newspaper in the world, new podcasts to listen to, email to check, updates to Twitter and Facebook arriving every three minutes in little corners of the screen — it’s no wonder people have short attention spans. There’s simply no way to get through the sea of information navigating a sailboat. You need a speedboat to manage the choppy waters, with a strategy to skip and skim as fast as possible.

Lament

Despite the abundance of short text, I still lament the trend. The less I write, the happier my project teams are. If I could deliver everything in a handful of haikus, I would be the most popular writer in town.

Text in this long guide

Reduced to a few callouts

Users jump with joy

The shorter documentation is, the more likely people will read it. But at some point, brevity doesn’t translate into simplicity. It translates into obscurity. Knowing the exact point that happens – when text I’ve shortened lacks clarity and only becomes confusing – isn’t always apparent. It depends on the context the reader brings.

The same people who clipped back my copious callouts into a few marketing bubbles would have also pruned this post from 2,000 words to 200. Would that make the text more valuable? Just as there’s a balance between simplicity and obscurity, there’s a balance between length and learning. More people might read a short text, but a longer text yields more learning. Is there no pleasure in learning anymore?

At any rate, as technical writers, the era of brevity invites us to emphasize short forms of instruction. As such, I present to you, patient reader, a list of the top 10 short text deliverables, optimized for the online reader:

• Quick reference guides
• Screencasts (1-2 minute)
• Visual callout guides
• Role-based guides
• Interactive rollover screen tutorials
• Instructive blog articles
• Online quick reference sites (example)
• Laminated job aids
• Cafeteria table tents
• Standalone diagrams and illustrations

These formats may not be ideal in all situations, but the trend is clear: shorter guides, more visuals, and less text, please.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

The first step in organizing help content is to refine the existing words on the buttons, tabs, labels, and dialog boxes. When those words aren’t enough, you can supplement the interface with more text to help users achieve their goals. Some technical writers refer to this supplementary text as narrative text, others as instructional text.

I don’t have a specific methodology for reviewing interface text. I’ve reviewed hundreds of student essays in my time, and despite the rubrics that departments dream up to objectify and standardize the review, rubrics always fall short for me. They’re an afterthought to try to organize your thoughts. I typically just read through a text and have a general reaction to it. Despite my resistance against rubrics, my thoughts on reviewing interface text can be grouped into five general areas: clarity, position, brevity, convention, and informativeness.

Clarity

In looking at the words in an interface, pay attention to your gut reaction. Where does it not feel right? Are there phrases or words that jump out at you as being off? Oftentimes the interface fails to use the right word to describe an action or concept.

As I mentioned in my Technical Writer as Outsider post, determining what’s clear and what isn’t clear becomes problematic if you’re an insider to the product, having attended countless meetings discussing every aspect of the application’s terminology and design from the beginning.

Even if you’re an insider, as you look closely at the text in the application, read it carefully and analytically. Try to misinterpret it. See it as a new user might, and wipe away all your assumptions. What information is required to understand the sentences or labels? Where do you think users will become confused? Focus on these problem areas first. Replace obscurity with clarity. Switch clunkiness for plainness. Strip away fuzziness with accuracy.

In a culture of scanning and skimming, it’s easy to become desensitized to poorly constructed sentences and imprecise meaning. But when we put on our language glasses and look closely at each sentence and word to analyze its meaning within the context of the screen, we start to see the gaps more clearly. Knowledge of grammar and style is helpful in heightening awareness, but as Chris Atherton points out, even reading good writing can make your literary senses more acute. For example, after reading this psycholinguist’s essay — They get to me — about her love affair with pronouns, you’ll start looking more carefully at the words you use in your sentences.

Position

Clarity isn’t just a matter of choosing the right words. Clarity also comes from putting the right words in the right places. Proximity increases clarity. The text you add should appear next to what it describes. Mike Hughes expands on this idea and says that users are drawn to action points on a screen. He recommends putting the text just a little “downstream” of the action point. In one of the best essays on user interface text, Instructional Text in the User Interface, Hughes argues,

User assistance occurs within an action context—the user doing something with an application—and should appear in close proximity to the focus of that action—that is, the application it supports.

In other words, position your help text next to the place on the screen where the user performs the associated action the help text describes.

Hughes says users usually skip static text positioned away from points of action. Their line of focus moves straight to the actions they can do on the page. The Microsoft Developer Network also echoes Hughes’ point:

Users tend to read control labels first, especially those that appear relevant to completing the task at hand. By contrast, users tend to read static text only when they think they need to. (User Interface Text: MSDN Library)

Practically speaking, you can forget about users ever reading the static paragraph that you add below the page title. They’ll move right past it as if it wasn’t even there and instead focus on the buttons and other actions they can do on the page. Add your help text next to those action spaces.

Brevity

If there’s one undeniable principle in crafting interface text, it’s brevity. Interface text needs to be as brief as possible for two reasons: users tend to skip over large chunks of text, and the available real estate for help content on the interface is extremely limited. About all you have available is a tweet, or 140 characters. One tweet per screen, if you’re lucky. “Too much text discourages reading,” MSDN says. “The eye tends to skip right over it—ironically resulting in less communication rather than more.”

Because space is limited, you may need to provide a link to more information. A small help icon or link next to a point of confusion doesn’t tire the eye and allows you to expand on a topic without rigid space constraints. The help link can open a pop-up window in an online help or just provide a pop-up within the interface itself. The following screenshot shows how WordPress handles interface text for the Excerpt field, which appears below each post you write.

Moving text into the interface -- how WordPress handles confusing fields

Keep in mind that while your users may appreciate copious on-screen text the first time through, seeing the same abundance of text every time they perform a task on the screen can begin to clutter their view. This is one reason to use help links that open up more information: the help information only appears for those readers who need it.

Convention

Follow convention as much as possible. Your users have a history of expectations built up from thousands of hours of web browsing and application use. Users expect certain conventions that should probably be consistent in your application as well. Put the help button in the upper right. Use the standard names for buttons and labels, such as Save and Print.

One of my colleagues tells me that on one of his projects, the designer has decided to call the home button “Front” instead of “Home.” I’m not sure why. Following convention may seem a bit boring, but it decreases the learning curve for users. It’s one of the reasons Adobe tries to standardize their toolbars and interfaces across all their creative suite products — so users can carry over learning from one application to another.

When you’re stuck on names for buttons or other interface text, consult applications of a similar kind. For example, I was recently stuck on a button label in a calendar application I’m documenting. What word briefly describes the act of deleting “the current event and all subsequent events”? I checked out Google Calendar to see what term they used. While I didn’t use their exact term — “All following” — their usage helped me come up with a better solution.

Informativeness

One of the greatest challenges in editing interface text is locating all the messages tucked away in the dark corners of the application. Most often this hidden text appears as uninformative or illiterate error messages programmers have either written or ignored as they coded the application.

For understandable reasons, error messages slip by most checkpoints and make their way into production because they are hard to find. Many writers never see these messages unless they’re abusing the application. And once they appear, it’s hard to remember what you did to trigger the message. My favorite error message is “Object reference not set to an instance of the object.” This message seems to be pervasive across all .NET applications I’ve worked with. Though I’ve read and re-read this message dozens of times, I have almost no idea what it means.

How do you find all the messages in an application? How do you make sure you haven’t missed an error message, or an email notification, or an ungrammatical success message? Just because you don’t see it on the interface doesn’t mean the text isn’t there.

Sometimes programmers have a file that contains all of the language in an interface, especially if the application will be translated. Other times the messages are scattered throughout the application code. Quality assurance is no doubt aware of many of these messages, since they try to purposely break the application.

However you find the hidden text, when you do uncover one of these nuggets, they tend to provide golden opportunities for editing. I have rarely seen an error message or other notification that was informative. Usually these messages are phrased with as much obscurity and generality as possible. Programmers are sometimes careful to express in euphemisms what would otherwise be an admission of ignorance. Instead of “I don’t know why this error occurred. Sorry, maybe we’ll fix it someday,” users see “Unhandled exception has occurred in the application.”

Other times the reasons for the error are too complicated to explain in human terms. So we end up with “The conversation ended, or timed out, or resulted in a null exception.” It may be accurate, but it’s gibberish for users.

In Avoid Being Embarrassed by Your Error Messages, Caroline Jarrett recommends writing error messages in a way that tells users how to fix the problem. Piggybacking on Rhonda Bracey’s advice, Jarrett says,

… Try to give users some hint about what to do next, such as: Please try again, switch everything off and on again, jiggle the plug, uninstall the software, or whatever.

Jarrett cites an example. She says one writer changed a message from “Low Voltage Error” to “Check Power Cable.” The revised message focused on the fix rather than the problem and resulted in a “reduced support calls and certainly improved user confidence.” By focusing on the fix, you can make your interface text more informative to your users.

I’ve only scratched the surface with interface text. But if you stick with these five areas: clarity, position, brevity, convention, and informativeness, you’ll have a good starting point for improving interface text.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

I somewhat disagree. When readers complain that writing is too long, what they’re really saying is that they’re getting bored. The length isn’t so much the problem as the content. They want to click elsewhere because they’re bored.

What Is Boring?

To better understand what defines boring, let’s look at a random article from the Technical Communication Journal – a journal that is known for being a bit on the dry side. As an academic journal, the authors perhaps feel constrained by scholarly conventions. These conventions involve omitting personal experiences, avoiding the use of “I,” backpedaling from straightforward speech, and taking as long as possible to get to the point. Here’s a passage in the August 2009 issue from an article about mentoring:

In our survey, we asked participants to explain any “risks” (Society for Technical Communication 2002), “constraints,” or “difficulties” they may have encountered in their mentoring relationships; however, we allowed respondents to interpret these terms as they wished. Their responses, which were lengthy and covered multiple issues, indicated that they defined these terms in a broad sense. Three readers (two of the authors of this paper and a graduate student) analyzed the responses independently and parsed each response to the questions into individual comments—the length of which was determined by topic rather than by grammatical unit. To ensure the reliability of these divisions, all three readers had to agree on the length of the resulting comments. As a result of the divisions, there were 267 comments.

Realizing we may have biased the responses with our example (“a student who asks her mentor for a letter of recommendation when she has performed poorly in the eyes of the mentor”), we tagged any comment that related to that example as a “metacomment” and excluded these responses from our analysis. We also tagged participants’ comments that were unrelated to the issue (such as comments about mentoring in general or comments about the questionnaire) as metacomments. That left us with 208 comments to categorize.

The readers then tried to categorize the comments using an existing taxonomy, Eby and Allen’s (2002) multilevel taxonomy of protégé’s’ negative mentoring experiences (see Appendix B), that we had revised to reflect a mentor’s perspective. For example, we took Eby’s category, Lack of Mentor Expertise, and changed it to Lack of Protege Expertise. We felt the taxonomy might be a valuable tool for organizing the results. We soon discovered, however, that the majority of the comments from our survey did not correspond to Eby and Allen’s taxonomy.

Although some of the comments fit into some of the categories (29%), most of the comments (71%) did not fit into any of the five categories in the Eby-Allen taxonomy of negative mentoring experiences. Therefore, the readers took the remaining comments and grouped them by topic and created a new taxonomy (as described in our Results section) to better reflect the academic mentor’s perspective. (p.250).

Are you bored yet? What exactly is it about this article that makes it boring? The authors do focus a lot on the process instead of the point. This may be a required academic convention for journal articles, but if so, perhaps it could be moved to some footnotes or an appendix. It’s the equivalent of describing the writing process. Can you imagine a post that contains the following?

First I made a series of notes on a piece of paper. The paper was 8.5 x 11 and purchased at Staples at a discount. The fact that the paper was purchased at a discount did not bias the way we used the paper. We made our notes in a dual column format, with pros in one column and cons in the other column. In my notes, pros is synonymous with advantages, while cons aligns itself with disadvantages, though it also included negative connotations. As I began to make notes, I also compiled a brief bibliography on the topic. Readings included both websites, blogs, and articles. STC publications were given priority as well as articles submitted to tc.eserver.org. With each reading, I added notes on index cards, which I then taxonomized into a hierarchical structure sorted first by author and then by date. The index cards were lined and initially encased in thin plastic.

It’s dreadful writing like this that partly discouraged me from academia. In addition to emphasizing seemingly unnecessary details, the writing omits any personal experiences.

I suppose I expose my biases here, but good writing mixes the personal and professional. In other words, good essays have a balance of personal experiences and ideas. You may only be a “narrative presence,” as Ted Conover explains, but don’t completely omit the personal if you want your ideas to come alive. The experiences you bring to the topic not only give the essay a engaging spin, personal experiences also usually bring in story, which is essential.

Story

Your writing will ultimately bore readers unless you can hook them with story. Story is the sine qua non of writing — without it, chances are what you’re writing will be lifeless.

When I refer to story, I’m not talking about Cinderella or Huck Finn narratives. Any time someone or something struggles to overcome a problem, that’s a story. The problem could be purely conceptual, such as a philosophical idea you struggle against. Better stories have characters (perhaps the character is you) that experience a change to overcome the problem, but that change isn’t always necessary. A bare bones story simply needs conflict. However you tackle it, when you approach your posts from the perspective of story, the writing gains propulsion and keeps the reader engaged.

A while ago, I read a chapter in a book — Ivan Tors’ 1979 memoir, My Life in the Wild — that provides somewhat of an example with the power of story. Tors is probably an author no one has ever heard of. And rightly so — his prose is pretty bad and unenlightening. I bought the novel at a thrift store looking for some cheap adventure nonfiction. However, in his chapter “In Cold Sweat,” he nails the story technique.

Ivan is an animal expert accompanying a video documentary team in Kenya. On an outing to observe migrations of animals from the dry Serengeti to Lake Victoria, his jeep’s water pump gives way, stranding him miles from camp. As he starts walking back to camp, he realizes something is following him. He writes,

As soon as I began my long walk, I heard the yellow grass rustling behind me. I turned and looked. There was an enormous female lion following me, just sauntering behind me. I knew that I must not run or I might provoke an attack. When a 500-pound body pounces on a human back, something is bound to give. I knew what I had to do. I must disregard her and do nothing that would excite her, but I could not help thinking about my friend who was killed by a lion, and this did not do much for my morale.

At this point, Tors has our attention. The conflict is clear: he is stranded in a hot desert with a lion surreptitiously following him. Because the reader is somewhat hooked, Tors can move us in whatever direction he wants now. He can launch into exposition about the behavioral patterns of lions, and we will still remain attentive because of the story. And this is exactly what he does. Tors explains,

Lions have formed the habit, during the many millions of years of successful existence, of surprising their prey. This means stalking them from behind against the wind and jumping on their backs when an attack is least suspected — usually breaking the back of the prey. Antelopes, for their part, have learned that frontal attack is unlikely and that spotting al ion and not running is the safest tactic. If an antelope herd sees a lion, they usually turn toward the lion and stare him down. The lion, thus discovered, becomes confused, and then disappears to try his luck on another herd of antelopes that perhaps will remain unaware of his presence.

Were it not for the story, this exposition about the behavior of lions would quickly tire us out. Likewise, if we were only fed details about the experience, without the information of the lion’s behavior, the story wouldn’t be as engaging. It’s the combination of personal experiences and ideas narrated against a conflict that makes writing interesting. (I scanned the “In Cold Sweat” chapter and converted it to PDF format here if you want to read it.)

You may object that I’m comparing apples to oranges with my examples. Clearly the Technical Communication Journal’s articles follow one style, and Tors’ literary memoir another. However, regardless of genre, if you follow the story, mixing personal with professional, you can usually keep the reader’s attention page after page.

For example, an article on mentoring could perhaps begin with an anecdote about a mentoring relationship that went sour, which then prompted the author to survey other academic mentors as to whether their mentoring relationships were also strained and why. A 17 page article on mentoring could be peppered throughout with personal experiences and reflections from different mentors about the root causes that destroyed their mentoring relationships.

I recognize that this is not the academic way, that injecting the personal element presents the possibility of bias and of conclusions drawn from anecdotes rather than empirical research. While I recognize this, I think you can’t omit the personal without suffering the consequences: with few exceptions, the reader will get bored. The personal element plays an especially critical role with blogs, since many readers value the honesty and transparency that comes from personal exposure.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Soon after, I started designing the help content for the application. I brought a few of the quick reference guides to a meeting — they all felt it was perfect and I felt good about what I’d done. And then little by little things began to unravel.

The quick reference guide I showed the team

We met on at least three separate occasions, each time reviewing the help content. Since I designed the information in a specific layout in Adobe Indesign, these little adjustments were tedious. Sometimes adding information made the text extend beyond the allowed column length. Or taking away information left odd-looking gaps. To compensate, I adjusted the spacing and kerning/leading in places, and sometimes removed an image or added one.

Designing for an information space (the double-sided page) before the information was locked down was a major mistake. Each adjustment required not only an adjustment of text, but often an adjustment of design.

Nearly a week before the release deadline, I announced that I could also include an online help file, since the online help would merely involve copying the same content from the quick reference guides into a short online help file. I already had a stylesheet set up from another project and would only need to tweak a few colors of the skin.

I manually copied the text from the quick reference guides into the online help, and then I decided to check the accuracy of the help a few more times to make sure it was still correct.

Here’s where it started to get a little more “interesting.” In all my meetings, dev and QA were absent. The meetings included the project manager, product manager, audiovisual, the sponsoring business department, and the interaction designer. We relied almost exclusively on the interaction designer’s prototypes as we discussed functionality, workflow, and special cases. I somehow had the impression — perhaps because the interaction designer kept affirming it — that the prototypes matched the development environment, or that the development environment would need to match the prototypes before the release.

Little did I know that, in fact, there were significant differences between the prototypes and the dev environment, including bugs in workflow and printing processes that the developers couldn’t fix and weren’t planning to fix. I ran through my instructions half a dozen times, walking through each step and noting the discrepancies.

As I had already copied the quick reference guide content into the online help file, I now had to make twice the amount of updates: one update to the quick reference guides, and another update to the online help.

After working deep into the night before the announced code freeze, I finally delivered the six quick reference guides that I’d promised along with an online help file that mostly acted as the web interface where users could download the guides.

I learned several important things about quick reference guides from this experience. First, I really should have created the material in an online help file first. If I design the quick reference material first, I spend too much time adjusting the design instead of focusing on the accuracy of the content. It’s better to create the quick reference material at the end, like icing on a cake.

Second, I should never fully trust anyone on a project. I don’t mean this disrespectfully, because I work with competent, talented professionals. But no one has the full picture of how the application will truly work. The quality assurance (QA) engineer usually has the clearest picture. The program manager and project manager are often living in a slightly different world, full of a vision of how the product should work and how they expect users to interact with it, but sometimes they’re missing important nuances in the actual implementation. The interaction designer builds prototypes and assumes the developers will build them to spec, but since the prototypes are usually HTML-based, and not in Java or .NET, variances are inevitable.

Despite the helpfulness of QA, they largely take orders from the interaction designer, developer, and project manager, so even QA can’t totally be trusted. They’re only knowledgeable about the current state of the application, the bugs they’ve logged, some awareness of the bugs that will actually be fixed or ignored, and expected delivery dates. They’re infamous for changing things at the last minute without telling you, because it’s tracked in their database according to the system they set up.

To avoid information surprises, I recommend you gather your information from every source on the project. Remember that each person has part of the truth, and when you get enough pieces, you’ll see the whole.

While you’re still gathering the information, don’t start designing your quick reference material, because the information and application is still in a state of flux. Instead, throw that fluctuating, still-under-review, subject-to-change text in an online help file until the content is locked down.

After the help content is truly locked down, not only will you only have to copy and paste once, you’ll know the app well enough to have a clear idea about the essential tasks you need to pull out. Once you do have the essential information, you’ll only have to design on your double-sided page layout once.

Have you had any lessons-learned experiences creating quick reference guides? If so, I’d love to hear them.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

1. Eavesdropping on customer conversations
2. Putting a personal face on your company
3. Increasing the reach of your announcements

Eavesdropping on Customer Conversations

You can eavesdrop on customer conversations by subscribing to queries that search for specific keywords in the Twitterverse. To subscribe to a Twitter search query:

1. Go to http://search.twitter.com and type your product name (for example, Camtasia).
2. Click Search. As needed, refine your search by adding + before words you require and – before words you want to omit. You can also enclose phrases in parentheses.
3. Click the Feed for this query link (circled in the image below) and add the feed to your news reader, such as Google Reader.


Link to the RSS feed for this Twitter search query

Tip: While you’re setting up product search queries, head over to Icerocket and set up the same keyword search across blogs and other online sites.

Why exactly would you want to eavesdrop on Twitter? Michael Arrington says Twitter provides companies “an excellent early warning system to flag possible brand implosions.” In other words, when people are complaining about your product, you’ll be well aware and may even head off a product crisis.

In fact, Arrington has an entire post narrating his experience of twittering negatively about Comcast. Arrington writes:

Within 20 minutes of my first Twitter message I got a call from a Comcast executive in Philadelphia who wanted to know how he could help. He said he monitors Twitter and blogs to get an understanding of what people are saying about Comcast, and so he saw the discussion break out around my messages.

(Thanks, Anne, for the link.)

Puting a Personal Face on Your Company

In the following Commoncraft video, Lee Lefever explains the point of Twitter is to allow your friends to know what goes on in your life between the emails and blog posts. Almost no other virtual medium allows this glimpse in to the personal space of your life as Twitter does.

To put a personal face on your company, you can encourage your product evangelists to twitter. I follow Betsy Weber, a product evangelist for TechSmith (makers of SnagIt and Camtasia). Betsy travels a lot. It’s interesting to see where she’s going (often the latest conference) and what she’s doing. I do feel a little closer to SnagIt and Camtasia by following her on Twitter.

I also follow Sharon Burton, a product manager at Madcap Flare. Her presence on Twitter makes Madcap more accessible to me. While I was beta testing Flare 4, I once expressed that it was a little discouraging. Seeing my comment, she called me to talk about my concerns.

Increasing the Reach of Your Announcements

Although using Twitter to only broadcast announcements isn’t good Twitterquette, it’s a good idea to include announcements about upgrades, new products, special events, etc., in your Twitter feed. A lot of people are drowning in RSS feeds, and they can easily miss a title floating through their RSS readers. Others have stopped using RSS altogether and rely solely on Twitter. Emails are problematic because they’re associated with all the other spam in your inbox.

By including announcements in your Twitter feed, you increase your reach. Additionally, those who search for keywords on Twitter will more likely find you.

Are you using Twitter in your documentation? If so, I’d like to hear how.

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.