Over the last few months, the User Education Team has developed a content model and a supporting style guide. Our evaluation of various documentation authoring tools a few months ago resulted in our choosing Author-it—a tool none of us was familiar with.

In our discussions about our content model, or how our information is structured, sometimes we kept drifting into talking about what Author-it would allow us to do. It was an easy line to cross. The way you approach reuse and other considerations can change based on what tool you use.

But overall, the optimal way to structure information isn’t dependent on a tool. That’s probably why our team lead kept steering us away from thinking about whether aspects of our authoring approach and information architecture would be supported in Author-it. There were parts of our discussions that blurred the lines—we would sound like we were talking about the tool, but we really weren’t.

Such discussions highlight what I’ll refer to as the core component of technical communication.

That component is the heart of the term technical communication—that is, communication.

The secondary part of that term, technical, refers to the subject matter we are communicating about. But it could also refer to the method we choose to author, organize, and deliver the content, which these days rests in technology.

Technology changes. Communication channels and content delivery mechanisms change. We have Author-it today, but something more fitting for our organization and our needs may come along in a few years. DITA has spread through much of the tech comm space, but who’s to say something more effective won’t come along in the future, or that DITA won’t evolve (see what I did there) into something better?

Yes, the technology changes, but the core principles of communication don’t.

› Continue reading…

Bookmark It

Hide Sites

Many times when I think of surveys, I think of the Animaniacs cartoon with the ladies who asked the three Warner siblings, “Would you like to take a survey?” There followed many questions with every imaginable permutation based around George Wendt, movies, and bean-eating.

Recently I conducted an online survey on the training and help materials for System X, a Web-based app for office staff. I didn’t ask a single question about George Wendt or beans. My two main goals were:

1. Find out how good the training was that the respondents received in person
2. Learn how much the respondents use the training and help materials in the application and how effective the materials are

Basic Results

I ended up with sixteen questions, some of which were demographic. According to Qualtrics (the software I used), 497 people accessed the survey, and 420 people completed it. However, I found as I analyzed the results that some respondents skipped questions and didn’t really fill it out completely. Still, about 230 out of 340 worldwide offices were represented in the result set, and I’m happy with the relatively high response rate.

As a bit of background, we have an online help system and a training page for this app. The training page has links to role-based quick reference guides in PDF and video demos in Flash. The help is your typical old-school tripane WebHelp with index, search, and so on.

Here are some key findings (numbers taken from those who responded, not the overall 497 or 420):

• 42.7% were not aware of the quick reference guides
• 28.3% were aware of QRGs but never use them
• About 25% have used QRGs at least once
• Average effectiveness rating out of 1 to 7 is 4.11 (so just above moderate)
• About 85% print QRGs when they use them

› Continue reading…

Bookmark It

Hide Sites

I’ve been reading Ginny Redish’s book, Letting Go of the Words: Writing Web Content That Works. It was a bit slow at first because the early material is pretty basic. And I came into it with the preconception that it wouldn’t apply much to documentation, since we write help systems and manuals.

In light of our team’s search for the tool that best meets a set of specific requirements, I’ve decided that Redish’s book has everything to do with what I do—or what I should be doing.

My Beef with Tri-pane Help

If you’ve been reading this blog for a while, it’s no secret to you that I’m not a big fan of tri-pane help. I think it’s dated and is associated in people’s minds with unhelpfulness.

But in our search for a tool that will give us a more robust Web output, I’ve discovered the main reason I don’t like tri-pane help.

› Continue reading…

Bookmark It

Hide Sites

In our quest to get more decision-making weight in the organization, the User Education team is putting together a set of standard practices. You may wonder why we don’t already have these. To put it succinctly, we still have to carve out our place in the IT department’s project lifecycle so that at least most projects have a user education component to them. Since there have been only a few of us, we’ve operated mostly by our own judgment, each person doing what he judged appropriate for each project.

We’ve come to realize that if we want our department to take us seriously and give us the place we want, we need to be equipped to justify the decisions we make on what user education products are right for any given project. One of the things I’d like to see happen in our team is to develop a menu of products, each with a specific definition and an explanation of the situation(s) in which we would recommend that product.

I’ve taken a first shot at this. I’d like your help to flesh this list out, the descriptions, and the reasons you’d use each one. In the comments, please let me know what I’ve left out.

Quick Reference Guide: One-to-eight-page guide that contains reference information, repeatable tasks, or some combination of these. Used when users have small number of tasks or will frequently need to refer to charts, tabular data, and so on.

Quick-Start Guide: One or two sheets that explain the steps for setting something up. Could also provide a set of most common tasks. A throw-away document. Focus may lean toward one-time training.

Short Guide: Thirty-to-forty-page document that provides task steps and reference information. Used when there is too much information for a quick reference guide.

› Continue reading…

Bookmark It

Hide Sites