Yesterday, one of the members of our team told me about her interview with a subject matter expert the day before. Because of his experience with the processes with which a new application is going to assist, this fellow was asked by the project team to be the SME. When my coworker went to talk to him, he said, “I’m sorry I’ve wasted your time. I’ve looked at the system only once.”

There was a fundamental problem there: The SME thought that his job was to know the application inside and out. My teammate began asking him questions about the process, and they talked for two hours.

I’m guessing that when this guy was asked to be the subject matter expert, no one told him what that meant. He assumed that it meant he was supposed to become the expert on the application. That will come later as he actually uses it after its launch. As a SME, his role is to provide the technical communicator with the understanding of the business processes that the application complements. It’s the interaction designer’s—and the technical communicator’s—job to be the expert on the product.

The moral of the story is plain: Help the SME understand that his role is to help you learn the business processes or other matters that relate to the product you’re documenting. There are other people who can tell you about the product itself. Without that fundamental understanding, a SME may start on the wrong foot and provide irrelevant information or little at all. Our team member improved the situation by asking the right questions to get her SME talking about the processes.

When you’re reading over your documentation, does it sound like a robot wrote it? I’m sure mine does.

One of the benefits of starting on a new project is that I can try out new things. This time around, one of those things will be a more relaxed style using contractions. I thought of this because when I’m writing other things, such as a journal entry or creative piece, I tend to use contractions. They’re a natural part of speaking. So as I was writing some help, I started to include some contractions without even thinking about it.

I caught myself, but I asked Tom’s opinion on the subject. He’s in favor of using contractions in documentation, making the point that when you have a frustrated user, he or she is going to want to talk to a person, not a robot. Therefore, make your documentation sound like it comes from a real person.

Something like using contractions is so simple, but I got the idea from somewhere that contractions are illegal in formal writing (must have been in kindergarten—I think that’s where I learned everything that I can’t remember where I learned it). I’m going to let myself write more naturally and see if that results in more user-friendly help.

Then I, with Pinocchio, will be able to say, “I’m a real boy!”

Our organization has a style guide, and I’ve come to appreciate that fact. Style guides can seem like a relentless master who has bent you to his will, and now his every whim is your reason for breathing. I’ll admit that I don’t agree with everything in the guide. However, without a style guide, life is chaos.

(more…)

I’m starting a new help project, and I decided to take the opportunity to try something a little bit different. The help is going to be context-sensitive, probably WebHelp. In previous CSH projects, I provided an image of the screen and placed numbers in places where I was going to describe the functionality. Below the screenshot were corresponding annotations.

I have usually kept the how-to content separate. In one project, a separate manual described procedures for the various roles in the system. In another, I included how-to information in a second section in the table of contents. This time, I’m going to do something in between.

(more…)

The last STC News and Notes email highlighted a BBC News article entitled “Web users ‘getting more ruthless.’” The gyst of the article, which is based on a report by usability specialist Jakob Nielsen, is that people are doing a lot less Web surfing than they used to. People go online to accomplish specific things and are not given to wandering and dawdling.

I don’t think this surprises anyone much except for Web marketers, who try to grab people’s attention (and end up annoying them instead) with ads and widgets. But what does this mean for us as technical communicators? Are we contributing to people’s success rate of accomplishing their tasks online? If not, how do we?

(more…)

This post continues my comments on the results of my experiments using RoboHelp Packager for AIR on a WebHelp project.

General Bugs

Having Back and Forward buttons is great. However, in Classic Help, they didn’t always seem to follow my navigation path. I don’t use browse sequences (and I turned that feature off anyway in the AIR generation dialog), so I don’t think I’m misunderstanding the purpose of the buttons.

The Classic Help TOC seems a little buggy when the Favorites pane is open. Everything worked except when I had a bunch of books open and had to scroll to get to the last book. When I scrolled, I got behavior like the selected book or another book automatically closing, or the TOC would jump so I couldn’t see where the selected topic was. (If I scrolled back up, the auto-closing book would open up again.)

Where I had Captivate demos in a topic, a huge space was inserted before each Captivate demo about the size of the demo itself. The demos work fine, but that big space is an irritant.

(more…)

I had some time today for testing the RoboHelp Packager for Adobe AIR (isn’t saying “Adobe AIR” like saying “ATM machine” or “PIN number”?), so I went to town. I kept notes as I went. I would be flooding the Packager forum with threads after exercising the Packager, so I thought it would be better to not be the kind of guest who makes himself at home to the point of leaving his clothes and dirty dishes strewn all over the house. Instead, I’ll provide my critique here in my own space.

Please be aware that these are coming generally in the order that I made the notes, though there is some semblance of organization of related topics. And unless otherwise noted, I’m talking about the “Classic Help” layout, since that’s the one I tried first.

(more…)