I'd Rather Be Writing » Screencasts

Podcast: Organizing Help Content: Breaking Out of Topic-based Hierarchies

Tom Johnson — Wed, 18 May 2011 22:59:33 +0000

The recording is available in a variety of formats:

I recently gave a presentation at the STC Summit in Sacramento titled “Organizing Help Content: Breaking Out of Topic-based Hierarchies.” I would have recorded my presentation, but recording is not allowed. I did, however, record a practice run-through in my hotel room the morning before.

I included a variety of links here. If you want to view slides while listening, click the Audio with Slides option.

Comparing the practice presentation to the real presentation, the practice presentation ended up being about 15 minutes longer. This means I had more time for questions and discussion during the real presentation. Some participants gave me great feedback in the discussion and follow-up afterwards. This presentation is only one part of an ongoing journey in my effort to solve the findability problem with help content.

Blog Sponsors

From DITA to VITA: Tracing Origins and Projecting the Future

Tom Johnson — Wed, 02 Feb 2011 07:55:14 +0000

With my recent reflections on long versus short text, a comment by Michael O’neil made me wonder whether the “reading to do” mode equated with DITA’s task type, and whether the “reading to learn” mode equated to DITA’s concept type.

In researching this, I stumbled across a goldmine of an article on the History of DITA. The article (mostly by Bob Doyle) traces the evolution of structured authoring from its earliest attempts in the 1960s through the present day. The history seems to encapsulate all the major innovations of technical communication, culminating in the formulation of DITA.

According to this history, DITA can be traced from the following previous approaches and philosophies: Quick Reader Comprehension (QRC), Sequential Thematic Organization of Publications (STOP), Information Mapping, Minimalism, SGML, Docbook, and other innovations.

Tracing this evolution is fascinating. I’ve tried to read through some of the sources mentioned inasmuch as I could find them online. I’ll try to retell the history with my own commentary along the way. At the end, I’ll explain my own method for help authoring.

Quick Reader Comprehension (1961)

Around 1961, T.J. Matthews, an editor/publisher at the West Coast Navy Laboratory, developed a Quick Reader Comprehension method (QRC) for reports to increase reader comprehension while also making authoring more efficient. To increase the comprehension, he invented a format in which he labeled each section with the main idea on the left, while writing the details are on the right, as shown in the image below.

Signposts in the marginalia facilitate scanning and accommodate both novice and advanced users because all users need "the gist."

Matthews explains the philosophy behind this format:

The recipients of an R&D report often differ widely in their subject matter knowledge, use for the material, time for study, and desire for study. They do, however, all have one thing in common. They all need to grasp the main points of the presentation (3-4). … the headings and marginalia that the scanner sees do serve as signposts that direct him to complete text descriptions. This provides a sort of random access effect. The report holder has an intelligent basis for deciding whether to study or skip any part of the material. (Quick Reader Comprehension, p.5)

In other words, the marginalia serve the more advanced user who only wants to quickly scan the material. The novice user who needs more detail can easily dive into more depth by reading the text on the right. Matthews’ technique tries to solve the problem of delivering the right amount of information to the audience given the variety of user needs and backgrounds.

Matthews also places a heavy emphasis on illustrations. Illustrations can serve the same purpose as the marginalia, allowing the reader to quickly scan through the document, reading the illustration captions and looking at the visualization of the information to grasp the whole of it. This is actually how most people read National Geographic magazine.

Matthews argues that “literary” (or text-heavy) approaches to technical writing often result from students graduating from English departments, where there is a constant focus on texts rather than graphic design. Matthews’ monograph itself is illustrated with graphs and other visuals to depict his ideas. He notes that students who want to enter technical writing need a solid background in graphic design, because “Art and science are not two things; they are two sides of the same thing” (Thomas Huxley in Quick Reader Comprehension, p.12).

To decrease the authoring time, Matthews creates a modular authoring process in which each section is a standalone topic that can be prepared and finished independently. This allows the authors to work on any part of the document at one time rather than proceeding sequentially through the material. Matthews explains:

“…each section or subsection is confined to discussion of a single topic. There is no cross-referencing. This permits the sectional topics to be prepared at any appropriate time and in no particular order. They are done piecemeal. This approach has several advantages over more usual methods. First, outlining is greatly simplified and relegated to one of the last, rather than one of the first tasks in reporting. Second, if the units are prepared during the course of the technical work, then large blocks of material are ready for use as soon as the problem has been completed. It is only necessary to arrange these blocks in logical sequence and write transitional sentences or paragraphs. Third, the reader benefits because the author is obliged to stick solidly to one subject at a time.” (Quick Reader Comprehension, p.6)

In other words, Matthews is moving toward a modular writing process in which you have a series of independent, self-contained modules rather than one long text. This speeds up authoring time and also increases reader comprehension because each section will have a stronger focus. This facilitates the reader who skips certain sections of a document and reads only specific areas.

STOP Storyboarding (1965)

The next major development comes from a publications department at Hughes-Fullerton Aircrafts. Walter Starkley explains that “the notion was to construct the proposal entirely of two-page modules, with text and any associated visual facing each other” (STOP, p.42). In other words, Starkley’s STOP method is probably the first quick reference guide.

The following image shows the STOP format.

The STOP method has a graphic on the right and text on the left. Content cannot exceed these two facing pages, and you must always have a graphic, even if you're only visually depicting your argument.

Starkley says some writers objected, noting that some topics called for more elaboration beyond two pages, and other topics don’t have visual potential for the required graphic. To address this, Starkley says research shows most writers switch topics after about 500 words anyway (the length of text allowed on one STOP page). For the graphic, they allowed the graphic to visually depict the argument or ideas instead of showing some object.

Because you had to write for a specific structure, the STOP method is one of the first instances of structured writing. The content could not be longer than two pages. The left facing page had to contain explanatory text, while the right facing page always showed a graphic. This consistent structure no doubt led to a predictable pattern for readers to follow.

The writers pinned these guides up on the wall for readers to look at. Because each two page module was self contained, “the reader [was] confronted with a self-contained and easily assimilated theme wherever he may open the document” (STOP, p.47). Again, this self-containment of topics is another instance of modular writing.

Notice the STOP method’s emphasis on illustrations combined with text. This emphasis on illustrations will be mostly forgotten by the time DITA develops.

Information Mapping

Robert Horn builds on some of the previous concepts of labeling and modular writing, but he also introduces something new: information types. Horn identifies seven major information types:

Blocks in the domain of relatively stable subject matter can be sorted into seven basic classifications, which we call ‘information types.’ The seven information types are:

Procedure

Process

Concept

Structure

Classification

Principle

Fact

(Structured Writing as a Paradigm)

Horn then analyzes the optimal structures for each information type and develops an approach for each type. Horn also introduces the idea of “information blocks,” which are similar to paragraphs but more tightly focused on a single idea, and usually about 7 sentences (no more than 9, to fit with Miller’s Law of 7 plus or minus 2). These information blocks chunk the information into reusable components for “precision modularity.”

The following is an example of a document structured with Information Mapping.

Information mapping classifies information into seven main types and then recommends an optimal structure for each type. In Information Mapping, information blocks are used instead of paragraphs. These blocks are short, contain no topic sentences, are labeled, and are modular.

Information Mapping is still a practiced method for authoring, and there’s even an Information Mapping conference in Texas this week. However, reading about Information Mapping is somewhat difficult because Horn has trademarked the technique and restricted access to the material. However, you can see a before-and-after demo here.

Minimalism

The next major development is a concept called minimalism, introduced by John Carroll in his book The Nurnberg Funnell. The basic ideas is that learning takes place through action and exploration, not through reading manuals. The more information you can remove from a manual, the quicker you can get users into the application, exploring and learning for themselves.

Carroll has four main principles in his minimalism approach:

Choose an action-oriented approach.
Anchor the tool in the task domain.
Support error recognition and recovery.
Support reading to do, study and locate.

(See Application of Theory: Minimalism and User Centered Design, by Mary Lou Mazzara.)

In other words, minimalism isn’t just about reducing word count because people are busy and don’t like to read. Minimalism is grounded in learning theory: users learn by doing, not by reading. Get the user acting in the application. Focus your topics on real tasks the user wants to do. When the user makes errors in the application, provide ways to guide and correct the user.

It seems at this point that graphics and illustrations are no longer emphasized, because the application itself is the visual illustration.

In Managing Your Documentation Projects, JoAnn Hackos relates a story that illustrates how too much information can “get in the way of learning”:

In one case study, a publications group decided as part of a paper reduction goal to reduce the size of their hardware installation manuals from over 100 pages of text and illustrations to approximately 20 pages. They eliminated redundancy and cut unnecessary information in the process, but they never consulted the users. All the decisions to eliminate information and redesign the installation books were made by the technical writers and the developers.

The users, 98 percent of whom were trained company techniques, were asked to review the content of the new, shorter manuals for accuracy. They carefully corrected errors in the existing text. Finally, they inquired why anyone in their group needed 20 pages of text to install the hardware. Once they were asked, the technicians explained that all they needed was a picture of the board to verify that they had the right piece of hardware. (103-104).

In other words, by becoming familiar with user’s needs, we can often reduce the information in our manuals significantly, not just from 100 pages to 20, but down to 1 or 2 pages.

DITA

In the interest of time, I’ll skip past SGML, Docbook and go right to the more well-known cousin/successor: DITA, or Darwin Information Typing Architecture. DITA builds on some of the developments of these previous structured authoring approaches. For example, DITA emphasizes modularity of topics, with the idea that each topic is a discrete, self-contained unit that the user can read without requiring a larger context.

DITA also identifies structures for different types of information, but rather than identifying seven types, it simplifies it to three: concept, task, and reference. Each topic can be one of these three information types. The topics are then assembled through maps that can contain any number of topics.

DITA is also heavily minimalistic. The task types, for example, require a structure that limits content to just one short paragraph after the title, and also eliminates stem sentences that introduce the procedure sequences. So far, not much new.

Where DITA is different is in the emphasis on content re-use and the separation of content from format. Why the emphasis on content re-use? In DITA 101, Ann Rockley explains:

One of the largest impacts of technology on information development is the addition of so many new formats for delivering information. No one just delivers a user guide (book) any more. There is an increasing need for information to be delivered in multiple formats. (DITA 101, 114)

In other words, content re-use is important today because we have more deliverables to produce. This is particularly true due to the Internet, which introduce a need for web help, and with mobile devices, which require a mobile format.

Another strength of DITA is that its structure enforces consistency, so for every task type, readers will become accustomed to the same format. This structure is enforced through the XML architecture of DITA, which requires certain tags in certain orders. More consistency leads to greater usability in the document.

Most importantly, DITA allows you to re-use or single source topics into different deliverables. For example, you can create a guide focused on a specific role, or for a specific scenario; you can compile a lengthy guide or a short guide. Because you can select and compile topics at will, you can create a variety of deliverables that better address a specific user level, context, and need. Ann Rockley notes that this selection allows you to get the right information to the right user at the right time (DITA 101).

DITA's chief strength is that it allows you to re-use content easily. You can create myriad guides with different selections and combinations of topics. This allows you to address a wider variety of users, roles, scenarios, and other contexts. You can get the right information to the user at the right time.

(Image from Reuse strategies and the mechanisms that support them, ditaxml.org)

Because content is separate from format, DITA requires a rendering component to transform the XML (your tagged content) into an output. This is part of the beauty of XML — you don’t hard-bake the format into the content. You can apply a completely different style to the content without actually changing the content. However, customizing the stylesheets requires XSLT programming knowledge, so this also potentially a drawback of DITA.

Beyond DITA

DITA is an impressive format, so one might ask, what could possibly come next? Is DITA the most cutting edge approach to documentation, the culmination of years of refinement and adjustment?

Noticeably absent in DITA’s functionality is a collaborative, wiki-like component for working with non-writers, such as stakeholders, project leads, and end-users. However, Don Day, chair of the OASIS DITA Technical Committee, is working on a project that will combine DITA with wiki-like functionality so that DITA can be used as a collaborative tool for a wider audience.

Other developers are working on exporting DITA to a wiki format, and then back again (round-tripping). Lombardi software has developed a method for the export of DITA to Confluence wiki. This looks promising if you use Confluence.

Only Half the Problem

I like the idea of DITA. It should be the back-end technology behind nearly every documentation tool. It clearly has the potential to make authoring processes more efficient. However, DITA only solves half of the problem. Remember back in 1961 when T.J. Matthews tried to solve the problems he was facing with his QRC method? Matthews starts his essay by complaining how the scientist today entering the space era “faces insuperable problems in attempting to keep himself informed on what he needs to know.”

He then asserts:

The Quick Reader Comprehension (QRC) method of R&D reporting promises to make both writing and reading more productive. It is potentially capable of saving at least half the manhours that scientists and engineers spend in manuscript preparation, and of increasing greatly the amount of information that can be obtained in a given amount of reading time. (Quick Reader Comprehension, p.3)

It's equally important to increase user understanding as it is to improve authoring efficiency.

Matthews’ attempt is not just to create a more efficient authoring process, but to improve the users’ learning, their rate of information absorption and comprehension. DITA just provides more of the same content in different combinations — topics in long guides, short guides, role-based guides, scenario-based guides, online help, mobile help, and other forms. The ability to pull together topics in the selections you want is critical and a huge step forward, but remember it’s still the same topic content. And of course that’s the idea of DITA — same content, but wrapped in different packaging.

However, as a total help solution, we have to keep in mind the other half of the problem: helping the user understand the massive amount of information we’re giving them. DITA should be a component within a larger learning strategy, not the solution for learning. Users who look at DITA as the magic button for perfect user assistance are missing a key point. DITA does not significantly enhance learning in itself — it’s just an authoring efficiency.

Multimodal Learning

The innovation in technical communication today needs to focus more on innovation in learning techniques, not just efficiencies in authoring. As we know, users interact with help material in a variety of contexts. Sometimes they read to learn, other times they read to do. Some users are novices who can barely double-click a mouse; others can understand the code running behind the application. Some users are voracious scanners who turn page after page looking for information; others are visual learners who need to see in order to understand. Others need someone to explain tasks to them in person; others prefer interface tips and notes and they explore on their own.

No help material will provide a one-size fits all solution. Rather than simply regenerating the same topics in different outputs, what users need for learning is a multimodal help experience. Just as conferences that offer nothing but lecture after lecture bore their attendees, help material must also provide content in different modes. Not just help in different formats, but different modes entirely. These different modes will not only suit different users but will also reinforce learning with different senses.

The four categories of multimodal learning that help content might address are as follows:

Video (screencasts). Probably the single greatest tool for learning a software application is to see how to do it. Our minds are visually mapped. When we watch how something is done, we understand. No amount of descriptive text and screenshots can really communicate all the a user takes in by watching a two minute video. Lynda.com, a video tutorial site for hundreds of software products, is the probably most popular example of technical communication on the web.

Illustrations (quick reference guides). A user looks at an overview of the system to gather a holistic idea of how it works. A two-page quick reference guide (QRG) with an illustration fills this need. You can’t just extract this content from a topic in your online help, because the content is integrated into the illustration, which may only be a screenshot with callouts on it, but ideally it’s more conceptual. In my experience, the content has to be revised for the illustration. To make an analogy, a quick reference guide is to a reference manual as a poem is to a novel. It’s not just the same content — it’s compressed, it’s an overview. It captures the whole in a visual way rather than explaining the parts.

Text (wiki or online help). The user who wants to read the details, or who needs a quick answer to a “how-do-I” question, can consult the written material to find the answer. A wiki is often the best solution here in collaborative environments, because it takes advantage of collective intelligence. But an online repository of any help content also works as long as it’s searchable. DITA can provide a good format for this content.

Action (practice and exercises). As John Carroll rightly pointed out in minimalism, you only truly learn something when you act, when you do. Users need practice problems and exercises and if possible, a test system, where they can experiment and explore the ideas and techniques they are learning about. These invitations to act can be added as “suggested homework” at the end of videos or put into a training workbook.

There are other modes for learning, of course. For example, teaching. When you teach a subject, you learn it better than anyone else. But how do you incorporate this learning mode except in a classroom setting? Perhaps if your online help is a wiki, you can give every user his or her own space where he or she can make notes on key tasks. Or encourage forum participation to teach others. But since there isn’t a practical application, I omitted it from my big four above.

The acronym for these four main modes of learning is VITA. In Latin, this means life, which is appropriate for the balance of the approach.

VITA is an acronym for video, illustration, text, and action. These four modes of learning provide the right balance to optimize user understanding.

These four modes aren’t just the same content pushed out into other formats. They are modes of learning. Some might criticize my approach to say that it falls under training or instructional design more than technical communication, but these lines have always been blurry. Our purpose as technical communicators is not merely to communicate information, but to help users understand the information and to become power users of the application or system we’re educating them about.

DITA could be used in this multimodal learning solution. DITA might be a wonderful tool for pushing topics out as screencast scripts and training material, but in my experience, the same topic doesn’t work without significant alteration. Single sourcing breaks down when you switch modes in drastic ways — going from text to illustration, or from written to spoken communication.

For me, it’s less important to try re-using content as it is to create content in new modes. And that’s the key deception of DITA. DITA would have you believe that you can single source your way into every possible deliverable. In reality, you’re just making potatoes in a few different ways (scalloped, mashed, boiled). You’re still giving the user potatoes. VITA is a multimodal approach, giving the user a full array of nutrition options, so to speak. It educates and informs by touching almost every sensory input.

Blog Sponsors

Making Help Content Enjoyable to Read — Impossible Quest?

Tom Johnson — Tue, 25 Jan 2011 06:18:59 +0000

In my previous post (“Less Text, Please”), I argued that users want shorter texts. I also explained how social media and Internet sites have possibly rewired our brains to incline us toward shorter content — according to some, our gnat-like attention spans can only consume a few short paragraphs before tapping out. The Onion has a great parody of how a single block of uninterrupted text causes mayhem for readers (“Nation Shudders at Large Block of Uninterrupted Text”).

But while short texts are met with smiles and cheers, many of my blog’s readers suggested that raising up a standard of brevity may be misguided. In fact, in many contexts, readers don’t mind long texts. What readers truly want, they explained, is simplicity, and simplicity is not always achieved through brevity.

As long as we strive for simplicity, illustrate our ideas, and focus on business relevant content, perhaps even the most technical user’s guide (such as a Network User’s Guide, shown below) might become as pleasing to read as a novel.

Is it possible for help content to be as pleasing to read as a novel?

(Drawing based on a photo of Clark Gable.)

Reading Modes

First we must distinguish between two critical modes of reading: reading to do and reading to learn. The distinction between these reading modes is an idea from Ginny Reddish (which Caroline Jarret expands on here). If you’re reading to do, you’re searching for an answer to a specific question.

Here’s an example of reading to do. You’re giving a presentation using PowerPoint, and 10 minutes before your presentation, you’re trying to figure out how to separate your slide notes from the projected slide display. In this scenario, lengthy help text is your enemy. You want the answer in as brief a space as possible, and as quickly as possible. You’re reading to do.

Ginny explains this mindset in one of her slides:

From Ginny Redish -- reading to do

(See “Understanding Web Readers (and Non-Readers) — Creating Usable and Effective Web Content.”)

I’m sure you can guess which guy in the above slide has a PowerPoint presentation in 10 minutes. But consider this other learning scenario. You know you need to improve your presentation abilities, and you’re tinkering around with Microsoft PowerPoint. There are so many buttons and features on the ribbon. It’s really overwhelming. You’re not looking to learn a specific feature, just the tool in general. You may have set aside 20 minutes a day to learn PowerPoint. In this case, you’re reading to learn.

Help content will never approach novel-like pleasure reading when a user is operating in the first mode: reading to do. But in the reading to learn mode, there is potential for something other than the frantic, frustrated help-cursing mode.

In Reading to Learn Mode, Length is Irrelevant

Let’s stay in the reading to learn mode. As long as the content is business relevant, entertaining, and simple to understand, there’s no reason to doubt the reader’s ability to become immersed in the content for long periods of time. Length becomes much less of an issue in this mode.

I don’t have hard evidence for assertions about length, but in Wired, Clive Thompson notes that the most popular blog articles are about 1,600 words per post (“Clive Thompson on How Tweets and Texts Nurture In-Depth Analysis”). This is about a seven-page essay. Writer/editor Tim Rich notes an eye-tracking study from Poynter showing that users skim until they find relevant content, and then they read for longer periods of time. Many other readers tell me they regularly consume long novels, and even wish the novels were longer.

Clearly in some contexts, length is not a problem. When content is interesting, you can have it any length you want. In one of Tim Rich’s posts, he quotes comedian Jerry Seinfield, who says, “There is no such thing as an attention span. People have infinite attention if you are entertaining them” (“Attention Spans”).

I think most will agree that text can be long and still be acceptable to readers. However, the real question is whether help content can be long and still be acceptable to readers. If not, why?

Is the Genre of Pain an Exception?

Let’s consider a basic reality. Help content is in the genre of pain. It’s right next to the tax code, your car manual, and a trip to the dentist. But does help always need to be trapped into a category of boring text no one wants to read unless they absolutely have to? Must it always be on par with a trip to the dentist?

Going along with the dentist metaphor, can the dentist ever change the experience so that you actually prefer to lengthen the visit? His fundamental activities, drilling, sticking his hand in your mouth, doing painful things to your teeth — it’s never something you want to prolong. Just like the tax instructions, no one wants the experience to be any longer, for goodness sakes. The last thing we want to do is extend the pain, right?

But Shorter Does Not Mean Less Pain

Although we do not want to prolong the pain, shorter is not always less painful. In fact, sometimes brevity increases pain. Imagine a tax booklet instruction that was just two paragraphs long. To the accountant writing the instructions, trying to keep it “as simple as possible, but not simpler,” as Einstein says, he or she may look at the concise set of instructions and feel satisfied. But this concision will likely leave me in the dark. I’ll end up scratching my head trying to understand terms, wondering if I’m interpreting it correctly, wishing there were some more examples and clarification. The time I save with shorter text is balanced by increased confusion time afterwards.

What we really want isn’t brevity. What we want is simplicity. As Whitney Quesenbery points out, “the repeated complaint about ‘too many words’ isn’t really about the word count, but about the density of the information and how this makes us feel about the information.”

When you hand users a two-page quick reference guide, their faces light up with excitement because they think the application must be simple. Project managers are cheering as well because the brief instructions seem evidence of a simple application, which means they did something right.

A sample quick reference guide. Users assume shorter means simpler, but that's not always the case.

But in reality, a two-page instructional document (such as the one on the right) for a complicated application may only leave users confused. As users make their way through the quick reference guide, they may encounter even more frustration than they would with a longer guide.

In a world of extreme concision, the novice user may be especially lost, like a hiker with a dim flashlight trying to navigate out of a rough patch of woods. The dim flashlight may be small and easy to carry, but in this situation wouldn’t the hiker prefer a larger floodlight instead?

As I said, what users really want isn’t brevity or shorter texts. They want simplicity. Who wouldn’t mind a 20 page guide if it were full of clarifying illustrations, examples, screenshots, and maybe even a glossary?

Illustrations and Simplicity

If simplicity is the goal, not brevity, you can implement a variety of techniques to simplify concepts. One of the most important strategies will be illustrations. Nothing clarifies a concept more than accompanying it with an illustration that drives the point home.

Before I push illustrations too much, let me start off with a caution raised by Tim Rich. Rich says,

There are times when a striking image expresses something in a more powerful or accurate way, but there are also countless occasions when words are an extraordinarily moving or precise media, when words can do more, say more, show more or achieve more (“On Pictures and Prose”).

In other words, images are often overrated in their ability to communicate information. A well-written paragraph full of description can sometimes communicate more information than an image. But without getting into semantic contests between text and images, I think we’ll all agree that combining the two is almost always a winning strategy. To keep the reader’s attention as you move through concepts and strategies, insert a concept diagram on every page, separating blocks of text.

A concept diagram explains a concept visually rather than merely decorating the page with a pretty picture. The concept diagram reinforces an abstract idea through visual means. Here are a few sample concept diagrams from Robert Horn’s Visual Language: Global Communication for the 21st Century (p.60).

Concept diagrams from Robert Horn's book on Visual Language

As you can see, you don’t need to be a great artist to create a concept diagram. All you need is some basic graphics abilities and an idea of how to communicate your ideas.

If illustrations are so helpful in simplifying concepts for users, why don’t more technical writers illustrate their help? Several reasons:

Lack of graphic design skills (or feelings of inadequacy in a world of professional expectations).
Lack of conceptual material to illustrate (it may all be procedural).
Not enough time to create the illustrations you need.
Difficulty in coming with a clever way to depict an abstract idea.

All of these reasons contribute to a text-heavy help. But if writers were to focus more effort on illustrating help content (and not in an Ikea-like way), you would see a complete turnaround in the reception of help content. Length would become less of an issue, and readers would welcome help content openly rather than resisting it at every level.

Screencasts

Illustrations aren’t the only solution to helping users learn a complicated process. Videos are also key. A simple screencast takes just several hours to produce. The dynamic visual interface combined with your human-narrated voice can have a powerful influence on user learning, since it allows users to see tasks in the context of an interface.

I’ve written about screencasts and voiceover techniques at length on my blog, so my purpose here isn’t to explain techniques, but merely to suggest that writers include more screencasts. Screencasts should be a more common deliverable than they currently are. Right now, based on my interactions with other professionals, I’m guessing only 1 in 10 technical writers creates screencasts, even though screencasting software applications such as Camtasia Studio or Jing are simple to learn and use.

Relevant Content

Another element required to convert help into a more pleasing reading experience is to focus on relevant content. A lot of times, we technical writers explain how to use a software application, but we leave the details of the particular business context alone. I know that when I worked as a technical writer for a financial firm, I rarely wandered into business context and use, preferring instead to merely describe how to do various functions in the application.

Why didn’t I describe more of the business use? Financial analysis is complicated, and uses are multiple. I clearly ran into the edge of my knowledge of the subject matter and didn’t feel comfortable getting into more in-depth business strategies and uses.

However, often the business context is more important than mere how-to within the interface. Many users, especially tech-savvy ones, can get the hang of an application easily enough. Look at even the simplest of apps out there — Facebook and Twitter. People aren’t clamoring for instruction on how to post updates to these web applications. Instead, users are confused about how or why they should even use the applications at all. In what contexts would they be useful or strategic? Why is it that nearly everyone has a Facebook account, but only a fraction of these people actually uses Facebook? Same with Linkedin and Twitter. The instructional material about business use and strategy is perhaps lacking (or unpersuasive).

Most help material has the same problem. The writer explains how to run a report, for example, but doesn’t say why the report might be useful, or how you might interpret the report, or who would be the most relevant audience for the report.

As another example, look at Google’s Chrome comic documentation.

Chrome's comic documentation failed for me because it lacked business relevant content.

When this first came out, it looked cool. I tore into the first few pages with a new-found enthusiasm, because this format seemed to open up documentation into a world where it was fun and fresh. But after about five pages, I lost interest, as did many other people who started reading it. It seemed to get boring and somewhat irrelevant, as well as technical, and so I clicked elsewhere. A cool idea, still, but perhaps not enough focus on business relevant content. (By the way, I have not seen Google produce any more comic documentation since then.)

There’s usually an entire dimension to help authoring that is missing from most help material: help about the business context and use. That’s the manual I would pay for, not the simple how-to about tasks already intuitive in the interface. And when you start delving into relevant business content, you have the power to keep a user’s attention at length.

Conclusion and Disclaimer

I’m not saying all help material needs illustrations, screencasts, and business relevant content, because every application or project is unique, and clearly generalizations don’t always apply. But as a guideline to follow, help could be a lot better if it more often contained these elements.

If you do include illustrations, screencasts, and business relevant content, you might not need to worry so much about brevity and word count. Your users won’t glance at a giant block of uninterrupted text and throw up their hands in exasperation. They may even start reading page after page with interest, forgetting about the time or page number.

Blog Sponsors

WordPress Tip: Integrating a WordPress Blog into your Website

Tom Johnson — Thu, 09 Dec 2010 07:48:11 +0000

Integrating a WordPress blog into your website is one of the most common requests I receive as a WordPress consultant. Whenever someone asks me to do this, I usually recommend moving the entire website into WordPress. That way you can manage all the content in one place. The user experience is more seamless too.

If you’re interested in having me convert your website into a WordPress-driven site, contact me.

Here’s a 5 minute screencast showing a project I recently worked on. In this example, we converted an existing static website to a WordPress-driven site (grandriverhospitaldistrict.org).

http://www.youtube.com/watch?v=T3tt4J_5uss

Blog Sponsors

The Perfect Voice — Professional or Authentic?

Tom Johnson — Tue, 07 Dec 2010 15:15:55 +0000

The Perfect Voice

One trend I think we’ll see more and more is the decrease of professional voiceover actors in screencasts when those voiceover actors are merely reading a script they don’t understand.

As an example, watch some of the tutorials at lynda.com. The narrators may not be professional voiceover actors, but they are subject matter experts. You can tell they’re not just saying words they don’t understand. They’re narrating and showing intricate parts of the screen at the same time. They’re describing processes and tips with the right articulation and inflection that shows they understand the software. I’m willing to bet most users would trade a professional voice for an authentic voice.

It’s somewhat of a hard model to break free from. At my work, the norm is to have voiceover talent read a script, while an audiovisual producer creates the screencast. They must have a heck of a time matching the two up, because actually the audiovisual producer doesn’t write the script. The project manager usually writes a script, which is then cleaned up by a screenwriter who is not a subject matter expert in what he or she is editing.

As a result, you end up with a voiceover actor, an audiovisual producer, a product manager, and a screenwriter all working together. Sometimes you may end up with a motion graphics person and a graphic designer as well. That whole model is outdated, in my opinion. It’s cumbersome, heavy, and expensive. There are too many parts played by too many people. To expect a perfect synchronization is too much.

The traditional model for creating screencasts often takes too many people playing too many different roles. The process is heavy and hard to synchronize. What happens when, at the end of this process, you need to edit the script due to a change in the software? You have to go through the entire process again, involving all of these different roles.

Despite my feelings against the traditional model, I’m sometimes a willing participant. This week I played a silent role as a facilities manager in some still shots and video b-roll (background motion). The product manager wrote the script. He passed it on to a script writer who modified the script. They had a professional voiceover actor read the script.

With the recorded script, a techie played another user role to act out the motions in a way that matched the voiceover’s script. We had a photographer and his assistant come to take still shots of several users doing different actions with the product. The next day two videographers came and did the same but with action clips. There’s a motion graphics person who will fit all of this together, and probably another audiovisual producer. There was another person whose job was to coordinate all of this.

When we initially brainstormed the videos, we had in mind a This Old House narrator, or a Bob-Vila type of narrator — in other words, an expert who would explain the process of setting up Internet access and firewalls in a conversational, natural voice. I expressed my concern that a hired actor would struggle with this, but no, they said, actors do need a script but will do it naturally.

Once we got into the project, it was clear that the actor just read the script. He read it well, but it wasn’t transparently authentic, because when he explained where to plug in the cables, he read it too fast — the actor trying to match his words had to move his hand rather quickly. To expect the narrator to actually go through the motions too was perhaps too much.

Now that all the footage has been captured, I wonder if it will look real — the narrator reading words he doesn’t understand, with a montage of still shots and a couple of silent video clips. It will look professional, no doubt. But is it what users want?

My colleague Paul showed me a screencast he helped create this week. In the screencast, a professional actor against a green screen narrated a script about a new website. She explained various features of the new website, all the while moving her hands in the same expressive motion. Someone skilled in motion graphics put the website as the backdrop behind the narrator, panning around and making the graphics move a bit. My colleague Paul helped work on the script, along with the product manager. This video took months to produce.

In the end, it was about 3.5 minutes long, but it lacked all human appeal. The narrator (a hired actor) was too stiff and professional. It was clear she wasn’t an expert on the site. I had no connection with her or the video and just wanted it to end.

In an era of reality shows, transparency, amateurism, and authenticity, the model of the professional actor and the myriad of roles coming together to produce a short screencast is ending. We accept the amateur’s voice, as long as the content is relevant, accurate, and clear. We prefer real people who know what they’re saying over hollow voices and false inflections.

Blog Sponsors

“I need your help with some documentation” (Xtranormal Movies)

Tom Johnson — Thu, 04 Nov 2010 14:28:28 +0000

Last week my wife, Shannon, showed me a couple hilarious Xtranormal videos. The first is So, you want to be a lawyer? And then, So, you want to get a PhD in the humanities?

After watching these two, I couldn’t help but think of a scenario for technical writers. The following is a conversation I’m calling, “I need your help with some documentation.” The project manager represents a compilation of all the crazy things project managers have said to me over the years.

After I made the preceding video, I feared project managers would call me out for being unfair, so I made a second video that tries to reverse the portrayal and show technical writers in a less-than-favorable light.

http://www.youtube.com/watch?v=JtoVbwPqPYE

Blog Sponsors

Searching STC Resources for Information

Tom Johnson — Wed, 15 Sep 2010 12:00:58 +0000

One of the advantages of belonging to the Society for Technical Communication (STC) is having access to the rich information sources on technical communication. These sources include Intercom, the Technical Communication Journal, past proceedings from conferences, the Notebook blog, and more. Unfortunately, there isn’t a single search that allows you to comprehensively search all of these sources at once. I this screencast, I show you how to navigate and search the STC site to find information.

http://www.youtube.com/watch?v=7_xyVw06OZ4

Blog Sponsors

The Importance of Visual Communication, or How to Build a Dirt Sifter

Tom Johnson — Tue, 07 Sep 2010 05:28:34 +0000

Recently due to flooding in my window wells, I had to dig the wells deeper. I piled up the dirt and rocks around the outside, and then realized I needed to sift the dirt from the rocks because I wanted to put the rocks back in, but move the dirt elsewhere in my yard to re-slope it. To sift the dirt from the rocks, I needed a dirt sifter, also called a gravel sifter. I thought I could simply buy one at Home Depot, but they do not sell them. You have to make one yourself.

I searched online to find instructions to build a dirt sifter. There are plenty of sites, with no one single method for building a dirt sifter. For the most part, it involves a rectangular wood box with a wire mesh bottom. That sounds simple enough, but as I walked through Home Depot looking for these parts, I had many questions. What size should the box be? How spacious should the mesh be? Would the dirt sifter fit snugly on my wheelbarrow or slide off? Would I shake it in my hands? Would I roll it somehow? If I rolled it, did the sifter need wheels? How strong did I need to attach the wire mesh to the wood? And so on.

I did some research online to figure out how to build a dirt sifter. One guy had a sweet looking roller device on his dirt sifter, but no real instructions on how to build what he’s showing. Another site had one incredible diagram but not much else. Others failed to provide any visuals whatsoever.

It’s not enough to build a box with a mesh bottom. You have to understand exactly how you’ll be using it to sift the dirt. Shaking it manually? Using a trowel in a wheelbarrow? Somehow rolling it? If you’re shaking it in hand, you better have a plan for catching the dirt, and the whole box should be small and light. But if you’re catching it in a wheelbarrow, it needs to fit over the wheelbarrow, so it needs to be larger.

It wasn’t until I found the explanation on this site that I began to understand exactly how to build the dirt sifter. The explanation is full of photos for each step of the way. The author doesn’t assume much at all, and he even provides tips such as the following:

Nails or screws driven near the ends of a board usually cause the wood to split. Pre-drilling the screw holes will help prevent splitting.

I wasn’t born with innate handyman talent, so I needed all the info I could get. After buying the necessary resources and tools, I gathered them up in my backyard.

Gathering my tools.

I started screwing the box together. It seemed pretty easy at first. I drilled holes just like the instructions recommended.

It seemed pretty easy at first.

But then my wireless drill’s battery wore down, and I grew impatient, so I started to pound a nail in there instead. Ooops, the wood split.

The wood split when I used a nail.

I had to discard that piece of wood and use another scrap that I had a lying around the garage.

I attached the wire mesh to the wood using an metal strip I found at Home Depot. It was all pretty simple, but I was still wondering just how I would shake a box full of rocks and dirt.

Fortunately, the dirt sifter fit easily on the top of my wheelbarrow, and I could use my hand (with glove on) to sift the dirt. Here’s a short video showing how the dirt sifter works.

After watching this three minute video, doesn’t it answer all the questions of sifter mechanics that I raised earlier? Would a textual explanation be adequate or nearly as appealing to watch as the video? In my video above, you see exactly how the dirt sifter works — not so much the construction, but the mechanics of use.

I find myself moving more and more away from text when it comes to tech comm. While text is a good foundation for other materials, text simply fails to communicate and engage like visuals do. With a visual (whether an image or a video), you see so many details that you can’t convey briefly with text.

Case in point, I often help users on the phone with a specific application at work. I can listen to them describe what they’re doing, but I almost always prefer to share screens and watch them go through the process. When I do that, I can quickly spot what they’re doing wrong. Sometimes I see that the content they’re working with is copied over from Microsoft Word, or I see that they’re using an unsupported browser, or I see that they really are doing everything right and the system just has a bug in it. Visual communication is faster and more effective.

The visual communication doesn’t need to be professional grade. I’ve been making quick WordPress screencasts that take me about 5 minutes from start to finish (including the upload to Youtube), and no one has complained about the quality. I also often make customized screencast tutorials for clients. They love them. It clarifies things in so many ways, and it’s easier than writing instructions out by hand.

Text, by contrast, is tedious, cumbersome, confusing, and fails to engage the user. Text still has its place, but it’s more of a supporting actor than a lead role.

Blog Sponsors

Introduction to WordPress — Recording of WordPress Webinar

Tom Johnson — Mon, 02 Aug 2010 14:08:06 +0000

Last month I gave a webinar on WordPress to the STC CIC SIG, which is the Independent Contracting and Consulting Special Interest Group of the Society for Technical Communication. I recorded the webinar and am allowed now to make it available for free on my site.

The recording plays my voice only, and the whole webinar lasts about 75 minutes. You can view the recording in two sizes. If you want small dimensions (about 1000 pixels in width), which will fit on most computer screens, view this recording. The clarity is a little fuzzy because I resized it to be smaller.

If you have a larger monitor or higher resolution, view this recording. The dimensions are larger, with a 1440 pixel width, but the clarity is perfect, since it isn’t resized at all.

Since it’s a huge file, wait patiently for the screencast to load. Also, this is a long time to sit down and watch a tutorial, so you may want to view this during lunch.

By the way, if you don’t already know, I do WordPress consulting, so if you need to hire me to help you get started with a project, let me know.

Recording of WordPress Webinar

Blog Sponsors

24 Hours of Screencasts with Camtasia Studio

Tom Johnson — Mon, 12 Jul 2010 06:11:03 +0000

On Tuesday, July 13, TechSmith is create 24 Screencasts About Camtasia in 24 Hours. It must be fun to do screencasts at 3 a.m. If you’re into screencasts (and use Camtasia), these sessions should provide a lot of good information. They’re streaming the screencasts live here and are also recording them to publish later.