We held our team offsite event today, and one of the items on our agenda was lessons learned from the STC conference in June. I talked about some of the sessions I attended, one of them being the “What Is Structured Authoring?” panel with Neil Perlin and Sarah O’Keefe. They spent the entire session talking about what their definitions of the term “structured authoring” and how it benefits the writer, and never was the word “user” uttered until I asked them whether structured authoring—whatever its definition—held any benefit for the user.

Neil replied that structured authoring lends itself to having consistent content organization, which is easier for the user to navigate. This was the answer that I pretty much expected, but I wanted someone in the panel to talk about users. User experience should be central to technical communicators’ thinking.

As we were discussing this in our team today, I thought up and drew a little diagram on the whiteboard that I call the Experience Spectrum:

Whatever definition of “structured authoring” we choose, we can go to one extreme and, while being consistent within a team or organization, create a totally new experience. Users could, over time, learn to expect the experience we created. Or we could go to the opposite extreme and choose a structure or scheme of presenting information that is based as much as possible on user research. We just find out what users want and give it to them.

With this being a spectrum, there are varying degrees and mixes of both approaches.

I rarely advocate the extreme of anything, so I think the best practice lies somewhere in the middle. We definitely need some user research so we know what they are accustomed to and like, and then we can create an experience that doesn’t frustrate users out of the gate. At the same time, as professionals, we know some tricks of the trade and some of our engineering of the experience should be based on our expertise. I’m simply asking here that we let the users have some input on the interaction they’re going to have with our content.

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.

Read the rest of this entry »

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.

Read the rest of this entry »

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?

Read the rest of this entry »

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.

Read the rest of this entry »