I’m becoming increasingly convinced that a help system is the dead last thing that people use for assistance. (Sometimes, though, if customer support is sufficiently lacking, that’s the dead last thing.) No matter how much we optimize help systems to make the information accessible, we just may never overcome the bad reputation that online help has.

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?

Read the rest of this entry »

Much has been said about the problem the Society for Technical Communication has found itself in, including on blogs, Twitter, and email listservs. (If you’d like to see some posts about it, Sarah O’Keefe has provided a list.) I’ve deliberately kept quiet here until I had some semblance of perspective to offer.

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.

Read the rest of this entry »

In an effort to improve a set of Captivate demonstrations I created for an application, I have started adding diagrams to the introductory slides where the voiceover exceeds 20 seconds. It’s a fairly arbitrary number, but I had to draw the line somewhere. After the introductory slides, I go into the demonstrations, so things move along at a pretty good pace. But I recognized that I’d put users to sleep if I didn’t throw some graphics or diagrams in to illustrate what I was talking about in those first slides.

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.

Read the rest of this entry »

In the two projects I’m working on, I’ve been given the role of administrator in Atlassian JIRA, the application we use for tracking tasks and bugs. This has its pros and cons.

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.

Read the rest of this entry »

One of my colleagues asked another about changing the icon in Flare that you can use to indicate new or updated topics. The answer: Change it in the output. I see people in the RoboHelp forums ask for a comparable feature too. But it probably doesn’t matter because how much do users care what’s new in a documentation set?

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.

Read the rest of this entry »

Several weeks ago, Tom Johnson said on Twitter that he had decided to document software with bugs and all—essentially giving the facts—and then he would update the documentation as the bugs are fixed. A number of people replied, some of them in agreement. Tom also posted the other day on writing “fictional documentation,” admitting that he will still document how it’s supposed to work without the bugs if he’s distributing in a format that’s difficult to update or distribute.

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.

Read the rest of this entry »

I finally updated to WordPress 2.8 today. It looks a lot like the previous version, and I haven’t taken time to explore the new aspects yet.

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.

Read the rest of this entry »