I'd Rather Be Writing » length

Give the Perfect Gift this Season: A Laminated Quick Reference Guide

Tom Johnson — Mon, 20 Dec 2010 07:58:41 +0000

Quick Reference Guides as Christmas Gifts

I was surprised and mildly pleased this weekend to see my sister-in-law Karin give a quick reference guide or “cheat sheet,” as she called it, to her grandma for her birthday. The guide focused on accessing and sending email in Gmail.

Grandma was grateful and elated to see the work and detail that went into the guide, which was laminated and narrow enough to prop up next to her [ancient] computer.

Contrast this happy image, passing around the quick reference guide at the birthday table and listening to the joyful chatter, with the sound of the dreaded almighty thud that large manuals create as one feels the weight and panic of an eternal instruction manual.

Karen’s quick reference guide isn’t visually engaging or attractively formatted, but she did an excellent job in bringing out all the unconscious details behind checking one’s gmail — a key detail probably necessary for her audience. Yes, this entire quick reference guide (it extends onto the backside as well) just explains how to check your gmail. She avoids jargon and tech writer slang completely as she focuses on just what the user sees.

This Christmas, if you really want to show someone you love them, give them a quick reference guide that you uniquely create for their technical frustrations.

I asked my wife — wrapping presents on the living room floor tonight — what her reaction would be if I gave her a quick reference guide on Christmas morning. She thought for a minute, and then confessed that she already knew everything, so the guide would lack value. But if I could address a relevant need, she would welcome it.

It takes me days to write these kinds of guides at work. So this is not an easy way out of a more expensive gift. And it’s hard to know exactly what computer troubles others around you have.

But maybe if you focused the guide on a soft-skills topic, such as how to get rid of stress, or how to get children to obey you, or techniques for subduing your husband, or something quirky like that, it might be an approachable and fun gift. It would be a gift she would never forget, that’s for sure.

The whole experience confirms to me yet again that users welcome short guides with open arms while continuing to despise and reject long manuals.

Blog Sponsors

Simplicity in a 550 page manual?

Tom Johnson — Thu, 09 Dec 2010 15:33:28 +0000

One of my readers, Shweta, asks the following question:

I am a Technical Communicator working in a software services company in India. I have been reading your posts daily from a long time now.

I am developing end-user documentation for an access control product. The current application that I have is huge and so is the user manual (550 pages, which I am sure not even 55 users will read). It also has an over exhaustive online help (not context sensitive, unfortunately). A Quick Reference Guide (prepared for each of the applications; there are 5) is still not sufficient to let the user know everything.

Was wondering if you can guide me on reaching best to the users with simple documents.

I’m opening this up this question to the community for response. You can add your thoughts in the comments below.

Here’s my take on this situation.You have the right approach in creating several quick reference guides to accompany the longer, 550 page user manual.

However, don’t expect the quick reference guide to cover the same scope as the long manual. There’s no way that you’ll teach users all they need to know from a 550 page manual in a few quick reference guides. That’s not the point of quick reference guides. The point is to help get the user started, to introduce the user to the content in an approachable way. Learning takes place primarily from doing, so the key is to get the user exploring the application quickly. Give them some direction and guidance to begin. That’s all a quick reference guide needs to do. See more from me about quick reference guides.

Blog Sponsors

3. Avoiding a Sense of Rambling

Tom Johnson — Tue, 09 Mar 2010 15:26:25 +0000

A while ago I was gathering feedback on different tech comm deliverables. I asked a user if she preferred videos or written material when learning software. I thought she would immediately say “videos,” but it was a toss up for her. In her mind, videos involved long stretches of narration that included sitting passively at her computer, waiting for the narrator to get to her question but never really getting there.

A lot of people feel the same way about videos. In a recent post, Kristi Leach explains an attitude she once held about instructional videos:

I rarely appreciate video instructions, either–they take too long, because I’m pausing, following the step, playing, pausing again. I was having trouble imagining how videos were going to improve our help systems or fit into our schedules.

For Kristi, prior to her turnaround screencast moment, videos seemed to take too long and were difficult to follow along with in a step-by-step way.

When you write a script for a video (or when you create a general outline), you can avoid the problem of the eternal video — which I refer to as a sense of rambling — by simply keeping the video short. Don’t try to cover too much ground. You can generally speak about 100 words a minute, so keep that in mind with your script. 200 words is a good length.

If you don’t believe me, when you watch videos, look at the video’s time counter and note when you start losing your attention. My patience times out at about three minutes. So I always try to keep my videos at three minutes or less.

Video Length

Guidelines for video length are somewhat controversial. Part of the problem is that video content varies dramatically. If you’re watching an episode on Hulu.com, that’s different from a humorous clip on youtube, which is also different from an instructional video about a software application.

Video2zero conducted a study and found the “ideal run-time for web video 2.5 – 4 minutes.” Betsy Weber of TechSmith says, “For the blog, my goal is usually around a 3-5 minute video.”

Brooks Andrus says we should consider Twitter a model for brevity when creating videos. He explains:

… most [users] don’t have the tools or narrative capabilities to hold the attention of an audience for any real span of time. This is especially true in the screencasting realm which is why I’d like to propose the notion of TweetCasts–120 seconds or less of webcam or screen video. That’s all the time you get to make your point. If you need more time, break your content into chunks, give viewers a rest between segments and try engaging them through a different medium.

I agree with Brooks. As informal video producers, we don’t have the time to implement mesmerizing Hollywood cinematic techniques to keep our audience’s attention. It’s better to break long segments up into little chunks. It might be good to actually keep videos at 120 seconds, as Brooks recommends. Although sometimes you need up to three or four minutes to actually explain a feature, there’s no reason you can’t have several videos about the same feature.

Look at how Lynda.com approaches their videos. The following is a breakdown of videos about PowerPoint.

Lynda.com sample outline

This approach allows the user to skip to the part he or she wants to know. For example, in the above list of videos, I viewed only the videos with the eye icon next to them. Because the videos were chunked into small units, I could skip the video content I didn’t want to sit through. Small chunks give the user control and avoid the problem of never-ending rambling that I explained earlier.

Advantages to Short Videos

Aside from maintaining the user’s attention, keeping your videos short has several other advantages:

No worries about load time. A three-minute video rarely results in a file size of more than 10 MB. In contrast, with a 10 minute video, it could easily be 30 MB, which creates more problems when you deliver it. With large file sizes, you have to consider how to optimize the video. Do you reduce the visual and audio clarity? Do you force users to wait for it to load? Do you resort to streaming options? You don’t have to worry about file sizes and load time when your video is short.

You make fewer mistakes creating it. When you record a video, if you only have two minutes, you’re less likely to make mistakes than with longer videos. If the script is short, you can more quickly rehearse and practice the steps so you know what you’re going to say, what you’re going to click, and you can make sure all the glitches are out before recording. In contrast, with a 10 minute video, you set yourself up for numerous mistakes in both narration and demonstration.

Post-production is easier too. If you have a short video, it’s a lot easier to edit in post-production than a long video. With a long video, you may end up with multiple video segments on your timeline, with several audio tracks, each at specific points on the timeline. Editing an eight or ten minute video can be a nightmare in video choreography. Sliding over audio in one section can produce gaps in another section, and so on. It’s just a lot easier if the video is short.

No need for a TOC pane. If you have a long video, you usually need to add a table of contents so the user can see what you’re covering and when. But adding a TOC pane takes up precious screen real estate that usually you don’t have. If you record your videos at 1024 x 768, adding a 175px TOC pane on the left increases your video’s size to about 1200px, in addition to whatever space the browser frame takes up. You usually can’t assume your viewers will have that much screen real estate. If you shrink your videos, you often end up with fuzzy displays. In contrast, short videos don’t need a TOC because the purpose of the video is focused.

Active learning increases. If your video is short, you increase the sense of active learning that takes place. By active learning I mean you give users control to make decisions, to click to the video they want to see. This keeps the users more engaged. In contrast, if you force users to sit for extended periods of time in a passive state of mind, without allowing them to choose their own adventure, their minds turn numb. To keep their attention in a long video, you have to resort to all kinds of interactive strategies or cinematic techniques so they don’t fall asleep. Quizzes, branching, let-me-try situations, bending window panes that fly in and out, dynamic illustrations and diagrams — these are all good, but if you don’t have time to implement them, keeping your videos short decreases the need for these tactics.

It can be hard to keep the video short, because sometimes we feel we have to tackle an entire component in one go. But it’s not hard to break a video up into multiple subvideos about the same topic. And what viewer wouldn’t rather click on several two-minute videos than sit through a ten-minute video with an eternally rambling narrator?

Blog Sponsors

The Seven Deadly Sins of Blogging: Sin #3, Being Boring

Tom Johnson — Tue, 13 Oct 2009 14:00:28 +0000

Being boring is sin #3 in my list of the seven deadly sins (other sins include being fake, irrelevant, unreadable, irresponsible, unfindable, and inattentive). Perhaps a more tactful way of saying something is boring is to say the writer neglects to “keep the audience’s attention.” I’m always hearing about the short attention spans of online audiences, that readers only skim your content and spend a minute per page. Because of this short attention span, you’re encouraged to keep your posts short.

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

Chrysler Drops Long Car Manuals in Favor of Short Guides + Video

Tom Johnson — Thu, 01 Oct 2009 05:46:03 +0000

Chrysler moved their car manuals from the traditional thick paper manual to a shorter format accompanied by a DVD. Chrysler says the switch will not only save 20,000 trees a year, the videos on the DVD will also be more helpful to users trying to perform tasks. The shorter quick reference guides will still be 60-80 pages long (judging from the photo below, they also look more attractively designed).

Chrysler's new documentation strategy: short guides + video + DVD

With my emphasis on quick reference guides and video tutorials, I feel like I’ve followed a similar move as Chrysler’s. I do like to have a car manual in my glove box, but only for simple, quick information — what type of oil, what does this or that light mean, how do you change a bulb, etc. I don’t need to know the full array of reference information. When I need that info, I can look it up on a computer and print off the relevant topics.

(There’s a brief discussion on the latest New York Times Tech Talk podcast about the move from paper manuals to DVDs.)

Blog Sponsors

The Appeal of Adobe InDesign

Tom Johnson — Fri, 11 Sep 2009 14:20:40 +0000

Have you ever told a project manager that the instructions he plans on releasing with an application — instructions written by an intern who is here for a three-month stint — are complete junk and that it would be an embarrassment to the organization to give them to users? When you tell a project manager that, surprise, you win yourself a new documentation project.

That’s all right, because Joomla, the topic of the instructions, is something I’ve been wanting to explore in depth. I have to say, I’m pretty impressed with Joomla. As a content management system, it’s powerful, easy to use, and captivating (kind of like driving my new Nissan Altima 3.5).

As I rewrote the Word document (of course it was in Word), I decided to create it in InDesign. In a time when I keep hearing about content re-use and single sourcing, a lot of my projects are small, with just one deliverable needed, intended for a handful of people, most of whom prefer something brief. Rather than the one or two page quick reference guides that I usually push, I’ve been extending them to 8 or 16 page documents.

Working with InDesign is interesting. On the one hand, it’s not really a tool built for technical writers. It’s intended for people laying out magazines, brochures, other heavily designed print matter. As such, some things can be confusing. Cross references, figure references, a table of contents — get ready to search the help to figure these out.

On the other hand, the power of the InDesign is somewhat captivating. You’re only limited by your own ignorance. Every day I learn something new and say, hey, that’s cool. For example, I installed the Typefi Autofit plugin yesterday afternoon to enable auto-expanding text frames, which I specifically wanted for my note styles. It’s neat that a proprietary application like InDesign has so many third-party plugins.

You may feel that some of the applications you use are boorish and dumb. Not so with InDesign. InDesign is an application with intelligence and sophistication. When you learn it, you feel like you’re part of an elite club.

When you can’t figure something out, the Adobe Forums for InDesign are excellent. Unlike Feedburner’s forums, which are a wasteland of single cries for help with no responses, the InDesign forums are active, monitored by gurus, and you get informative responses within an hour.

But enough about InDesign. The real question is why bother to use such a powerful layout tool when I could create the content in Flare (or some other HAT) and single source to a printed output? That’s certainly an option, but styling the printed output from Flare doesn’t compare with the styling options in InDesign (at least not within my print CSS skills in Flare).

Also, when I’m writing in a HAT, I get the sense that space is unlimited. I write every little detail, adding topic after topic. I think of every possible scenario and question and document it. The result is a printed document or online help file that is not really readable anymore due to length. It can only be searched.

I know it may be an old-fashioned concept, but I think users want a short guide they can read. Sure, users want to search for answers to those arcane questions, but they also want a guide that’s feasible to get through, that isn’t a War in Peace type novel but rather a dozen pages that tells them what they need to know. When it’s under 20 pages and well-designed, with a readable, attractive layout, that’s a product that has high value for users. It’s a deliverable that project managers and other techies can actually review. As a user, it’s something that still fits into your life.

If you give someone a manual that makes an almighty thud, they don’t even open it.