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…)

We have a customized flavor of Agile development, and today as I was talking to one of the program managers about the next few cycles of work in a particular project, he said that the work in the last cycle or two was not yet defined. That’s fine; at least in our version of Agile, the work that was defined generally at the beginning is solidified as we go. Development is planned on an iteration-by-iteration (or sprint-by-sprint in some vocabularies) basis and more broadly on a cycle-by-cycle basis. A cycle contains several iterations of work, and the idea is to have a body of code that can be released to and used by the customer at the end of the cycle. The interaction designers prototype at least one cycle ahead of development.

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.

(more…)

The idea of not trying to guess what users are looking for in documentation has been bumping around in my head since the STC Conference. I was talking to my manager yesterday about altering my approach to help. So far, what I have done (at least in context-sensitive help situations) has been to think about the details of application screens—how to use the controls, where prepopulated data come from, what happens downstream, how to get displayed data changed—and provide information in those areas.

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

(more…)

I was thinking about this yesterday and ended up talking to Tom about it today. We work on projects that have asked similar things of us, but in other cases, our constraints are quite different. One example is security.

Let me illustrate. One Web application may allow users to complete a process that is not in any way sensitive in and of itself. So the help content for that application also is not sensitive, so it’s not problematic for it to be on a publicly accessible server. Even if the data that the users enter in the application can be sensitive or private, you don’t know what they’re entering by reading the help, so there’s no problem.

On the other hand, another application may help users in completing a sensitive process. By association, then, because the help describes that process, it is sensitive. I have found that generally, the projects I work on require more security than Tom’s.

This creates a challenge for our team as we work on standard and best practices.

(more…)

At the STC conference, I remember someone—possibly Scott Abel in a presentation—saying that technical communicators really ought to be out in the online support forums for the products that they document. I agree; in the forums you can see the problems that real users are having and what the answers are if anyone has provided them. Being the technical writer, you may know some of those answers yourself. But at the very least, you can find out how people are using the product and what frustrates them.

It seems that Adobe heard the call. Within the last couple of days, a self-identified “technical writer for RH working at Adobe” has begun participating in the RoboHelp forums on Adobe’s site.

(more…)

Last year, I was working with a producer in our organization’s motion picture studio to create a training video. He has done some work in Hollywood and knew Kirk Douglas. I griped that Hollywood doesn’t get the picture when people pay to see certain kinds of movies and they don’t make more of those kinds—they continue to run garbage out of the mill though most of it doesn’t make much money.

This producer told me that they don’t make movies for us; they make movies for each other.

Now switch your brain over to your technical communication. Are we like that? I have joked myself that I get paid to write stuff that no one reads. However, probably because of my profession, I’m more likely to use the quick-start guides or check the help system while using something. Documentation is there in my consciousness.

(more…)

Do you ever have an experience that wakes you up and makes you wonder if you’re doing a good enough job?

I had to use a financial Web application today to take care of expenses for the trip to Philadelphia for the STC conference. It was completely unintuitive. I looked at the PDF manual to which there was a link right off the main page. It seemed like pretty high-level stuff. I blundered a little more before clicking “Help.” Just maybe there was some guidance there.

BZZZZT! Wrong answer.

After browsing the table of contents, I turned right off. The list consisted of noun phrases that told me nothing. I wanted to know how to go about a certain task, and there was no clue in the table of contents about where to find that information. What was worse: No search or index. Just a lonely little “Contents” tab.

I found myself thinking the word “unbelievable.” And then I closed the help.

And then I asked Tom for help because he went through this process after going to DocTrain West.

This made me think about one of the applications I’m documenting right now. It has a financial component to it, and it’s not going to be intuitive to anyone but CPAs. The interaction designers have done a good job of making things fairly simple, but I can see someone just like me—who didn’t follow his dad’s advice to take an accounting class in college—trying to use the finance functionality and not having a clue.

I have to remember the child’s taunt: When I point at someone else, most of the remaining fingers are pointing back at myself. How usable and accessible is the content I’m providing? How well am I helping this poor Joe accomplish what he needs to do and understand the system without having to explain the ins and outs of accounting? It’s a point to ponder.