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.

Read the rest of this entry »

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.

Read the rest of this entry »

This topic has been knocking around in my head for a while now, so it’s about time to post about it.

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.

Read the rest of this entry »

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.

Read the rest of this entry »

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.

Read the rest of this entry »

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.

Read the rest of this entry »

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.

Read the rest of this entry »