I’m more and more persuaded that quick reference guides and videos are preferred formats. Brainwashed by Tom Johnson? Maybe. But users of an application where I’ve provided these materials have provided feedback about them, and not much about the online help. If something’s not right with the QRGs or videos, people are noticing much sooner than if something isn’t right with the help.

Don’t get me wrong—help has its place. But I think its place is as an information repository that acts as a backup if the quick reference guides and videos don’t do the job.

But how to get people to go to the QRGs and videos first? Easiest is probably from the help system. But if people don’t go to the help, how will they find these materials?

In the aforementioned application, we have the traditional “Help” link in the header. But the QRGs and videos are found by accessing a training menu from the landing page. Typically, training and help have two different aims; one is to instruct before or during the task, and the other is for answering questions or troubleshooting. Because people want to know how to do things, they go to the training rather than the help, even though the help also contains “how to” information.

I’m thinking that our applications should start containing links to “Training” or “Training/Help” and not just “Help.” The first things to come up would be an FAQ and a menu of QRGs and videos. If users doesn’t want those, they can navigate around the help system as usual.

I’m not sure exactly how this would work with context-sensitive help, though. Some feedback I’ve gotten suggests that context-sensitive help is preferred over getting the same generic help topic each time. Maybe the help for the specific page of the app still comes up, but there’s a menu at the top or in a sidebar linking to the FAQ, QRGs, and videos.

Calling the materials “training” instead of “help” may be splitting hairs and even tricking users, but it may be a more effective way to lead them to the things that will get them the quickest assistance.

But I’ve come to the conclusion that maybe this is a crisis STC needed—an impetus to get us all thinking together about how to improve the model, how to offer more direct benefits to the members.

We’re past the point where talking about what previous officers did is going to help. I bought a house about two years ago and still am not happy with some of the ways the previous owners did things or left things for us, but my wife has pointed out that it’s our house, so we need to deal with it. Yes, previous staff and officers at the main office made detrimental decisions, but going over that can do only one positive thing: to show us how not to do it. Once that lesson is learned, it’s time to move on.

The Dilemma: Return on Investment

A significant part of the quandary here is that STC offers certain benefits, but many people want to see more tangible benefits. An existing benefit is networking; people have found jobs and gotten contracts because of people they met through STC. This is not true of everyone, and I’m sure for some it’s not for lack of trying. Some want to see benefits come more directly out of the dues they pay. The quandary comes in the fact that people are going to want these benefits now, particularly because of an impending dues increase. But right now, STC needs to get out of the shortfall, where the board will then be in a better position to reevaluate programs and revenue sources—in short, to get STC on surer financial footing and offering more benefits to members.

So, in effect, there’s a bit of a gamble here, folks. If you’re an STC member and you want to see more direct benefits, you’ll need to see in what ways you can help STC survive 2009. Fortunately, STC has indicated that they plan to release periodic progress reports that let us know how they’re doing in reducing the shortfall. But now is the time to step forward and offer your input. Your voice will be heard.

One of tech comm’s current challenges is showing value to employers. It’s ironic that STC finds itself trying to demonstrate value, not just to the world, but to many of its members. Thus, many members find themselves trying to justify both their jobs and their STC membership.

The Value in Communities

Being a chapter president, I have realized that a lot of the responsibility for providing direct benefits to members falls on the chapters and special interest groups (SIGs); as the STC bylaws state, “Communities are a signficant way that STC provides value to its members.” I think there’s a disconnect between this statement and the whole money issue. The STC site quotes a bunch of people who talk about how much the networking has benefited them. For a lot of people, this networking happens on a chapter level.

I admit that for me, the most value comes out of participating in the chapter. Some of the main benefits STC names are the salary survey and the job bank. But those help us only when we’re looking for a job or negotiating pay. And I would guess that many of us aren’t doing those things most of the time. (Though right now, there are probably many more doing this than eighteen months ago.) Other benefits, like webinars and the yearly conference, cost money beyond annual dues.

A video by Carolyn Kelley Klinger and Mary Fletcher Jones illustrates my point by discussing the value of belonging to the Washington, DC chapter, while glossing over membership in the overall organization.

I think one of the answers to STC’s mission to prove its value to its members is to enable the communities to do more. I sincerely hope that STC won’t cut off the pass-through funds to the chapters that come from member dues.

How about an Idea?

Few people like someone who criticizes yet doesn’t step forward with solutions. Though my intent isn’t to criticize, I still would like to pitch an idea of the way STC could assist the communities in providing more benefits.

There has been a little discussion on the presidents’ listserv about having more local or regional conferences. I think these could have more strength and benefit if the STC offices pitch in. STC has contracted with certain hotels for the next few summits, but after that, they could go to having the international conference every other year. On the off years, they could help organize and execute a few regional conferences around the world. This means that out of every four years, a given chapter has perhaps two or three STC conferences to participate in: one or two summits and a regional conference.

I see regional conferences as having a few benefits. First, they would be closer to the members, so they could be cheaper and easier to reach. It would be more affordable for employers to send members within the state/province or to the neighboring state/province.

Second, the organizing committee could find smaller venues that cost less to rent, saving STC, the communities, and the members money.

Third, it may be more feasible for smaller, local vendors to participate in local conferences, in addition to the larger vendors’ participation. This could gain STC more sponsors and allies.

Fourth, STC and the local communities who participate could divide the revenue from the conference. If STC is trying to reduce its financial reliance on the yearly conference, perhaps going to every other year won’t hurt the pocketbook. And multiple conferences in the off year potentially means more money for STC.

Note that I’ve never run a conference and am not intimately familiar with what goes into it. So I’m making a few guesses here for the sake of getting an idea out where it can be scrutinized. But I think that the main STC office (with people like Lloyd Tucker) could provide valuable oversight for regional conferences, increasing their success.

I understand that the yearly summit provides a location for the business meeting and other society-level events. So maybe having them only every other year won’t work. Or maybe on the off years, these activities can be virtual.

I realize that my ideas focus on chapters and geography, and they kind of leave out the SIGs. But I’m a chapter president, so I think in those terms. Perhaps there are some ways to adapt or take advantage of these ideas for the SIGs.

Change Is Coming

It is impressive that STC is over 50 years old. But though I don’t agree with everything Seth Godin said in Tribes: We Need You to Lead Us, I think of his assertion that age can be a detriment to rather than a strength of an organization. This argument is based on some organizations’ reluctance to step into the future, innovate, and change. If STC wants to survive long term, we are going to have to make some big changes. And I admit that I’m one of those people whose initial reaction is to resist substantial change.

I see it as a step in the right direction and a willingness to change that has caused STC leadership to ask for ideas. And the response has come. If you have ideas, please send them to stc(at)stc(dot)org. (Or if you’re an STC member, contact Bill Swallow through his site, techcommdood.com, and ask for an invitation to join the Ning STC Ideas group.) The board is listening and will develop a plan based on the input they receive. Time will show what the final effect of this collaboration is, but I believe STC can come out of this a much stronger, more beneficial, and more influential organization than before.

Some concepts are easy to illustrate, but I’ve run into some trouble with slides where the concepts described aren’t so easily translated to images. While talking with a colleague to get some brainstorming going for one video, I decided that some of the script and voiceover needed to be rewritten so as to be more easily illustrated. So I revised it, and we were better able to connect certain images with the concepts.

This has made me wonder how effective this could be as an exercise to judge the clarity of writing. It seems like a paradox at first: If text is already clear, why does it need illustrations? And I agree with that question.

I’ve said before that if a product is hard to describe, it isn’t designed well. But if text is difficult to illustrate, it may not be written well.

Notice that I’m not prepared to say this is true in every case, all the time.

By looking at this particular piece of text, though, and deciding how to illustrate it, I arrived at a simpler way to say what needed to be said. I was hesitant to do this at first because I had already recorded the original audio, and it’s a bit of a hassle to redo it. But because the new text is more satisfying and is easier to illustrate, I’ll ignore the inconvenience.

To return to the question named earlier—that of the purpose of using illustrations if the text is clear anyway—many people are visual learners. “Clear” text is a subjective description, and no matter how clear the text is, some people will just get it when they see it illustrated. Because of this, and because I don’t want to lose people’s attention during that first slide, illustrations at the beginning could significantly improve the quality and helpfulness of the videos.

This exercise of increasing diagrams and illustrations to assist visual learners could potentially help me increase the clarity of the text in any deliverable so that it benefits any who take the time to read or at least scan. At the very least, asking myself whether I could easily illustrate or visualize the text may help me write more clearly.

The reason I was given this role is that it’s required to move tasks and bugs through the workflows that our department has set up. In the past, I’ve had to pester project managers to move my items into the status where I could then resolve them to be tested. Usually, I didn’t remember to do this until I was ready to resolve the item. So the workflow wasn’t really work-flowing if you get my drift.

Now, as an administrator, I can usher my items through each step until I’ve resolved them. However, the problem with being a project administrator is that I get what I call JIRA spam. And lots of it.

Usually, when you want to see what’s going on with a JIRA item, you click a link to watch it. And then you get an email when its workflow status changes or someone adds a comment. But as an administrator, I get an email every time an item is created—doesn’t matter who creates it or to whom it’s assigned.

On the other hand, this can be a good thing. Because every team member is an administrator in JIRA for one of these projects (so they can also move items through the workflow themselves), I expect most of them have set up rules in Outlook to send the JIRA spam right on past their inboxes and into the trash or some other folder they ignore except when they empty it. But I’ve found that if I at least scan the title of the item as it sits in my inbox, I learn valuable information about changes that are proposed or planned in the project. And then I can go into JIRA and put a watch on items of interest to me.

So it’s an interesting catch. I get a lot of email out of JIRA, but it’s a way for me to keep abreast of changes. I just have to sift through the dirt to find the gold. Since the gold is there, I figure I’ll endure the dirt.

In this Web 2.0, connectedness-driven world, we acknowledge that to some extent, people seek out the most up-to-date information. If it was published in 2008, it’s ancient history. If it was published last month, it’s not as bad, but still not optimal.

In interviewing job candidates, I’ve seen portfolio samples with notes describing when the last update was and what the changes were. I can’t help but wonder how necessary that is. I’d say just include a “last updated” date and leave it at that. It’s interesting how many conventions in documentation are just that: holdovers from when everything was in print and people actually read.

The second colleague’s reason for not using the “new content” icons is that if users are accessing the help, they’re just getting in for a bit of info and getting back out. I agree. If they see a “last updated” date somewhere and it’s recent, that may reassure them back in the recesses of their subconscious. But for the task at hand, they want answers. The documentation itself is going to make clear whether it’s up to date or not—if it’s accurate, it’s up to date, regardless of the time stamp on it. Though a time stamp may help to instill some confidence.

I think an icon that says, “Hey, look at me! I’m new and updated content!” may distract users more than it helps. From what I understand, Flare’s icon is a topic with a star on it. There isn’t anything about it that readily suggests what the star means. So a user would have to go out of his way to mouse over it for a tooltip or whatever the mechanism is for discovering what it means. Most people probably aren’t going to take the time to do that.

Another thing that may subconsciously reassure users is making sure the documetation refers to the correct version of the product. If the product is in version 3.8.1, the documentation ought to indicate it’s for 3.8.1, or users may wonder how accurate it is.

I think time stamps and version numbers are probably sufficient to suggest accuracy and “up-to-dateness.” What do you think? Perhaps an interesting study would be to poll some users after they get into the documentation for a product; one set of users has a doc set with time stamps and version numbers, and the other has docs with none of these things, and in all other ways the exercise is the same. It would be interesting to see if there would be any difference in their perception of the documentation’s accuracy.

After Tom’s tweet, I had to think about where I stand on this issue. My conclusion is that I tend to disagree with Tom’s philosophy here. I don’t think the long-term documentation should address the bugs. I hope my documentation won’t change much (a dream in an Agile environment, I know), so I document things the way they’re supposed to work.

One answer to this problem is release notes. I have been putting release notes out for a particular project that we release every couple of months, and the response has been positive. Users are calling support or sending emails to report bugs and make enhancement requests, and it’s nice to keep them informed about fixes or other progress on those items.

I don’t know how many people actually read release notes. I think when I applied the patches to RoboHelp 7, I read the notes to see what bugs had been fixed. I expect users are more likely to be interested in them if they have reported or at least encountered bugs and realize that the release notes give them an update. We include a section listing known issues and workarounds.

Really, I think documenting the software the way it works with bugs is making more work for myself, so that’s probably the main reason I avoid it. I’ve got enough to do without changing the doucmentation whenever a bug is fixed. Release notes are easier—a much smaller deliverable whose focus is what’s changed and what’s still not quite right.

I don’t think users in general expect official documentation to reveal the product’s defects. (That’s for bloggers and columnists.) The release notes help feed the conversation with the users, saying in effect that “We heard what you said about the product, and this is what we’re doing about it. We’re improving the product because of your feedback.”

However, I realized why it can be good to wait a little while to upgrade something like WordPress. After I installed the new version, I got an error similar to the one displayed at menoob.com in a post about the issue.

I followed the suggestion there, though I used FileZilla to change the plugin file name. (Fortunately, of all the plugins that could have failed, this one isn’t critical.) Bam! I could sign in to my admin site. My thanks to the menoob guy.

When I ran into this error, I was frustrated for a minute. But I realized that since WP 2.8 has been out for a few weeks, there had to be someone else who had encountered the problem, figured out the solution, and posted it. I was right.

That’s my personal reason for not updating immediately when a new release is available. There could be problems, and it’s best to let more tech-savvy people take the bull by the horns and blaze the trails. (Now there’s an interesting image.)

Of course, if everyone followed this philosophy, no one would ever upgrade software because they’re busy waiting for someone else to do it first. But I’m glad there are those who don’t mind sticking their necks out and then finding the solutions to problems for the rest of us. So I will likely continue to drag my feet—but keep just ahead of the next upgrade.

• When the user pauses, either while using the product or using the documentation, there’s a problem. In one instance, the user stopped on a particular step, and after about a minute, I asked what he was thinking. He was at a step where there were two possibilities described, and he was confused by the fact that the first part described what to do if he didn’t need to take a particular action, but then it went on to describe what to do if he had to do it. All it would have taken to be clear would have been to direct him to go straight to the following step (past the second scenario).
• Warnings or info boxes may be totally correct and helpful, but they may not be in the right place. I had a couple that I thought I had put in the best place, but when the users came to them, they weren’t quite relevant to that particular part of the procedure. I just needed to move them to optimize the effect.
• It can be helpful to give some instruction or context about what to do once the task or procedure is ended. The first guy got to the end and wasn’t sure how to start over or begin a new task, and that was easy to fix.
• Make note of questions both you and the users ask. I mentally asked a question about a certain function, and the user asked it no more than two minutes later. Because I asked it, it was pertinent, but it was made much more so because the user also asked.

Finally, and this is reflected in most of the things I needed to change about my document: The concept that you start to take knowledge or understanding about the product for granted is true. That’s why doing the usability testing is so important.

The users helped find problems that I didn’t see. I did my best to introduce the test by letting them know I appreciated their feedback and suggestions, and at the end, I pointed out that they had given me some very specific things to change and improve. They were very willing to perform the testing in the first place, but I think it was a positive enough experience that they’ll be willing to do more in the future if needed.

One of the challenges, though, with testing the documentation is that it sometimes branches into commentary on the usability of the product. I assured them I would take their feedback about the application itself back to the appropriate people. Fortunately, the testing didn’t derail substantially into discussion about the app.

Up until now, with the users’ comments about how busy they are and how they need the most efficient reports and app performance (which I can’t blame them for wanting), I gathered that they had no time and interest in fostering a community among themselves. This application is used by more than 60 offices around the world and will ultimately end up at over 300, but I don’t know how much communication there is between these offices. If users are interested in just getting their work done in a timely manner, how much time will they want to take to help others?

Yesterday, an email came through that suggested that at least one person is willing. Or at least willing to ask questions. The email asked for a “bulletin board” of some kind for users to post questions and answers to. They find the process of going through the help desk too slow for the pace of their work.

In months of rolling this application out, this is the first time I’ve seen or heard of such a request. But if one person is asking for it, others may be thinking about it.

I can see the appeal of user-to-user forums. I did a questionnaire among a set of users of a different application a year or two ago in which they indicated their favorite ways to get help were to ask a coworker or manager as compared to using documentation or calling the help desk. People like interacting with peers rather than an impersonal documentation set or support agent.

I volunteered to help in this effort if it goes somewhere—right now, it’s still just the seed of an idea. Usually, the things that are requested the most get the most attention. Management won’t want to invest the resources to set up and manage a forum if it won’t be used. I wonder if the old line from Field of Dreams applies, that if we build it they’ll come. But a colleague of mine tried giving a set of users all kinds of Web 2.0 capabilities for an application, and not much came of it.

Anyway, we’ll see where this goes. But with talk going on about technical communicators needing to adjust their role and be content managers, including user-generated content, I’m willing to give it a try.

If I’m thinking shortsightedly, I’ll say, “I’m documenting this procedure” or “I’m putting together an FAQ.”

But what am I really doing?

Contributing to a positive user experience, I hope.

But is there more?

I think even the story about the cathedral falls a little short because a cathedral in and of itself is just something nice to look at. The worker with the most vision would say, “I’m giving people a place to gather and worship according to their beliefs.”

Technical communicators can be one of the few placed where we can have a real vision about the projects we work on. Especially if there is only one working on a product, as I do at work, that is an opportunity to grasp the big picture. Questions we should be asking—such as “What are the users doing with this product?” and “How is this product going to make people’s lives better?”—can contribute to our understanding of what impact the product actually has on individuals and groups.

I think this kind of vision helps with job satisfaction. If I can’t see beyond today, if I let today’s challenges capture all my attention, then my work tends to feel tedious. But if I look at the big picture of what I’m contributing to, then what I’m doing is of more value to me. For example, lately I’ve been working on some video tutorials for a certain group of over 100 people who will be stepping into new responsibilities in two weeks. I can become shortsighted and say, “I’m making some videos.” But if I look at the big picture, I’m helping someone save hours that would be needed to train these people in person, and I’m helping this new group learn some logistical tasks faster so they can focus on their most important work. That’s the vision for this particular project. Every project should have one—and it probably doesn’t take much asking to find out what it is.