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.

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!”

I’ve been thinking about this lately because somebody other than me develops prototypes for our applications. The fact is that whatever the interaction designer puts in the prototypes goes into the actual application. This means that if there is inconsistent capitalization in headings, that inconsistency lands itself in the final product.

That’s where I step in. Being a technical communicator, I’m driven by the need for consistency and clarity, and where I’m driven is crazy sometimes. I can be a little fanatical, but you know that there are users like me out there, and their opinion of the organization may suffer if they see a lack of polish in the software.

Sometimes, problems may not lie in outright inconsistencies; they lie in deviations from the organization’s style guide. No offense or belittlement meant to interaction designers, but they’re concerned with just what their titles suggest: They set out how the users and software interact with each other. It’s a subtle idea that part of the interaction is the text.

Perhaps it’s not so subtle. Interfaces contain graphics, including icons, that affect interaction. But much of the interaction relates to text. In cases where text in and of itself is correct but doesn’t adhere to the style guide, you may run into inconsistency between applications that should be consistent among themselves.

There are times when I have to forgo my personal preference in favor of what the style guide dictates, but at least I can rest assured that I’m contributing to the product’s professionalism. Interaction designers and developers in the project teams in which I work have become accustomed to and accepting of my input in matters textual. I feel like a hound on occasion, but someone has to take on that role. If there’s no watchdog in the barnyard, the fox will make off with the chickens.

And I like chicken, so I can’t let that happen.

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.

First, I’m planning to avoid the full screenshots and instead rely on smaller pieces of the application screens. The main approach here, though, is to have a two-column format for each help topic, the right column being something of a sidebar. The main column will describe the screen’s functionality. The sidebar, titled “How Do I…?”, will provide steps for doing certain tasks that relate to that screen.

The reason for this approach is that in my previous experience, it’s been a challenge to appropriately mix instructional content with informational. This approach, I hope, will provide both kinds in the context in which they’re needed by users. The two-column format will allow the user to scan each type of information and focus on the type he wants instead of having to scroll through a topic looking for the type of information he’s looking for. If he wants procedural, he can choose to look just at the sidebar and ignore the rest.

Since this is a small project, it will give me a chance to try this idea out and see how it works for a small user group before I start using this pattern for more projects in the future.

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?

Nielsen points out that one of the reasons people are becoming more successful at accomplishing online tasks is the use of search engines that can take them more directly to the Web pages they need. They don’t have to come to the home page and try to navigate through the menus as much anymore. Fortunately for us, help authoring tools and other software like Adobe Reader provide search capabilities out of the box.

One of the challenges for me while writing user assistance materials is deciding what information is useful. Minimalists argue that less (information) is more (useful and usable). But what if you cut out some content that is just what someone needs later to answer a question? Thinking this way, I get in danger of providing too much information, making it harder for someone to find what they need. Take away the haystack, and people don’t need to look hard for the needle.

No matter how much or how little content you provide, this is where “The Code” comes in. Good old-fashioned tech writing principles say that to be usable, technical content should have clear headings, logical organization, consistent and concise language, and diagrams (where needed).

I’m not a minimalist; as mentioned, I probably tend to err on the side of providing too much information. At least if I do that, I can still make the content easily navigable. This is where creativity comes in to technical communication. Unless you’re tied down by corporate dictates, you can put some thought into the best structure for your project’s purpose. Spend some time devising an organization and structure for your documentation before you ever start writing. Give it a friendly and inviting character. It doesn’t need to be inviting to the point of trying to keep the user inside the content, because that’s not the purpose, and as Nielsen has found, you’ll gain few fans; it should be inviting to the point of saying, “Hey, I’m going to help you get your job done. I’m the express lane, so come through here, get what you need, and get out.”

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.

Search, Index, Glossary

The Search (with word stemming), index, and glossary work as expected. I like the index and glossary better in Classic Help, perhaps because they work similar to the way they work in FlashHelp. However, I like the search in Uni-pane better because the search results give the user some context for each find. I wonder why the search isn’t set up the same way in the other systems. I’m sure having a narrow pane on the left isn’t as conducive to search results that show context.

In Uni-pane, I would like to be able to change fonts. The TOC headings are in Verdana, which isn’t my favorite, and my help is written in Arial.

Comments

I think the comments concept is on the right track. The comments XML file doesn’t save with an XML extension by default—I think it should. I’d have to tell everyone who wants to comment that they have to add the extension. The XML file also inserts “%20″ for spaces.

The Packager As an Extra Step

Packaging straight from RH as a single source layout would be quicker, and it would probably allow the dialog to remember the last settings used for that particular help project. As is, with the dozens of layouts I’m doing between several projects, I would have to be constantly changing the settings in the dialog. This would get complicated with variations based on languages and roles.

Suggestions / Wish List (Other than Those Already Mentioned)

AIR help doesn’t seem to support multiple languages other than displaying a translated help topic. It ignores the language setting of my output. I suggest a language setting in the AIR dialog.

I need CSH for Web (Java) applications; so far, AIR help supports only C/C++, Flex, and AIR applications. I tried linking from a basic HTML file on my computer to open the .air help file, and I got a dialog asking me to open or save it.

In my experiments, I’ve had to install every different .air file. My understanding was that users would have to install the runtime support once, and accessing every .air file after that would be transparent to the user. Maybe I’m doing something wrong here.

A brief note for anyone trying out the packager: Opening the .air file by double-clicking runs the installation with the option to “Run Now” or “Uninstall.” If you enabled the option to create a desktop shortcut and open it that way, it doesn’t try to reinstall. I found this in the RH Packager forum.

Conclusions

Adobe seems to be following a good line of thinking here with AIR help. But remember, users want simplicity. Having to install each help system as an application is asking too much of everyday users. The other most important things (and biggest wishes) to me right now are the following:

• CSH for Web/Java apps.
• Multiple language support.
• More options for customizing the appearance (colors and graphics, not pane layout).
• JavaScript support.
• Running the packager as a single source layout out of RoboHelp.

For the time being, the packager and AIR help aren’t robust enough for my deliverables. Thanks to Adobe for releasing beta versions of the packager and letting help authors give feedback. I’ll be keeping an eye on what Adobe does with the packager.

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.

Window Sizing

I had some problems with the output’s “physical” flexibility. I first tried Classic Help at 800 x 700 pixels, and the maximize and close controls didn’t appear until I widened the window beyond a certain point. So there seemed to be a minimum width that the window would gracefully handle. There also seems to be a minimum height for the AIR help so that the bar at the bottom with the “About” and “Preferences” links is hidden if the help opens at certain dimensions, such as the 700px or less.

The topics themselves in the right pane appeared to have a minimum width, even though the help I was testing had no such parameter set in the CSS or HTML. This caused the help text to run off the right edge and disappear, making horizontal scrolling necessary. I expect that behavior only if I had images that extended past the edge of the topic pane, but I expect the text to wrap properly.

At first, I thought the only way to resize the AIR help window is at the bottom-right corner. Then I discovered that I could indeed resize in one direction by clicking on the 1px-wide border of the help window, but because the mouse pointer doesn’t change to a resize handle, I found this out by accident.

After experimentation, I concluded that you have to have at least a 900 x 800 size before all controls appear correctly in Classic Help. (In Uni-pane, it’s right around 670px.) I think the help window ought to gracefully accommodate smaller window sizes.

Favorites

It wasn’t immediately apparent that the little arrow icon between the TOC pane and the Favorites pane means you can hide the Favorites. In fact, the arrow points upward, and an arrow pointing downward makes more sense to me.

I would like a way to set the Favorites to be hidden by default rather than showing by default and having to be hidden. This is how Web browsers work, so it is likely what people are used to.

JavaScript

I have some JavaScript in the help system I was using to test this; the scripts cause some hidden divs to appear upon clicking links and then to disappear again on clicking somewhere else. This completely didn’t work in the AIR file, even though the JS file I use was included in the baggage files of my RoboHelp project. I would like to see JavaScript better handled. (Perhaps it would work if the JavaScript were included in the page, but the reason for a JS file is that if you have to change the script, you change it in one place, not in dozens of topics.)

Customizing Appearance

I didn’t see any options for customizing the look other than picking a few PNG images for icons. I expected some skins or color pickers based on the descriptions on Adobe’s site. Customization of the look is limited to being able to choose from two skins per layout (or no choice in the case of Classic Help) and to select graphics for only five buttons. I would love to have greater control over the appearance so that I can make the help resemble the application it goes with.

That’s all I have time for at the moment. Part 2 is coming soon.

The manager hopes that most of the new development work will be done at the end of the second-to-last cycle. As he talked, I got a little idea: What if the last cycle of an Agile project were reserved for bug fixes? We have hardening periods before the release for fixing bugs and for the testers to make sure they’ve exercised and proven the functionality that was developed at the end of the cycle. But what about an overall hardening cycle for the bugs that haven’t yet been addressed throughout the entire project?

This would benefit the team and the customer, but I wouldn’t be talking about this if I didn’t think it could benefit me, the technical communicator.

Because, in Agile methodology, releases follow closely on the heels of the end of iterations and cycles, it’s challenging for the technical communicator to have the documentation for that release absolutely finished before the code has to start rolling toward production, let alone for the testers to give it a going over.

If there was a bug-fix cycle (or at least iteration, depending on the overall length of the project) at the end, this would give the technical communicator some time to catch up on those final details. Bug fixes generally result in functionality working the way it was designed rather than in a new implementation. Of that second category, much of the code tweaking is behind the scenes and would be transparent to the user experience. This means that the technical communicator could focus on making documentation accurate and wouldn’t have to worry about changes taking place during the bug-fixing frenzy.

So if you’re in an Agile shop, it could very well be to your advantage to put out the idea of hardening iterations or cycles at the end of projects. These periods would have to be included in the program manager’s project plan from the beginning so that the project wrap-up date isn’t delayed. You’d have less pressure, I’m sure the testers would breathe a little easier along with you, and the customer would be happier with the result.

One of the limitations of the written word is that we lose meaning as compared to in-person interaction. According to one of my college textbooks, Looking Out / Looking In by Adler and Towne, social scientists peg the amount of meaning we derive from body language at 65%. We also take a lot of meaning from vocal tone. We leave about 9% for the words themselves.

Writing does have voice and tone, but they’re not the same as in speech. Still, writing can carry emotion to the point that you can tell the writer’s mood. Writers have to be careful.

One day in college, I read a letter to the editor that was more of a guest column. I let it upset me, and I wrote a reply that was in the next edition two days later. While I was at work, a fellow writing tutor was reading the paper during some down time. She happened to be reading my response when I entered the room to chat. She said, “Whoa, this guy’s really upset.” Then she noticed who had written it, and she was pretty surprised.

Have you ever sent an instant message or fired off an email, then reread what you sent and realized that your words could be easily misconstrued? That’s one of the reasons it’s important to let emotional emails wait for a time so you can cool off and tone it down.

Think of how many ways the following phrase, if issued over instant messenger, could be taken:

“What are you doing?”

Just think of how many ways you’ve heard that question asked verbally, and all the reader has to do is pick one in order to interpret the words.

I have stopped time after time to rephrase something that I was about to type because the original phrasing could have easily been misinterpreted.

So much communication takes place these days without face-to-face or even voice-to-voice interaction. The lack of body language and verbal tones makes effective writing a challenge. It’s one of the reasons that writing is a craft; we have to carefully assemble words and sentences to create meaning. And it means that we have to make the words count.

I don’t think this cuts it anymore. Why? It’s the crystal ball approach.

I think my approach needs to be to look at why a user may be clicking “Help” on a given screen and then provide information that addresses that motivation. I don’t think users open the help system to satisfy an idle curiosity. They don’t want to spend the time for that. When they open help, it’s to get a task done or solve problems.

But the key here is that unless I get real users’ input, I’ll just be guessing or “divining.” So my manager and I talked about sitting with people while they try the system out—similar to or in conjuction with usability testing—and find out why they click “Help.” Having them tell me how they think the help ought to be organized would eliminate a lot of guesswork. We’re hoping to get this kind of thing organized soon. It could change the way I look at my writing, probably only for the better.