As you’re developing a help system and updating content, it sometimes becomes necessary to delete a topic file because the information is out of date or should be combined with other information. When you’re using both RoboHelp and Subversion, it’s easy to mess things up doing this. It’s important to delete the file in RH first to maintain its version of reality and lessen the hassle. But things have to be done correctly in Subversion too.

These steps go through the steps in general plus specific steps in parentheses for the TortoiseSVN client for Windows Explorer (currently version 1.6.10), which I use. The TortoiseSVN steps explain what to do in Windows Explorer.

1. Commit all current changes to the repository (right-click in folder > SVN Commit).
2. In RH, make sure no links or other references point to the file you want to delete. (To check this, go to Tools > Reports > Topic References to run a link report. Then remove the links that are listed.)
3. Click the topic in Project Manager.
4. Press Delete. (Note that if there are still references to a topic, when you press Delete, the confirmation pop-up asks about removing those references. I recommend you go back to step 1 so you don’t have to find and fix a bunch of broken links.)
5. Click Yes. This deletes the file from your hard drive and from RH’s awareness.
6. Update your folder to pull the file back in from the repository (right-click in the folder that contained the file, and then click SVN Update).
7. Delete the file (right-click file > TortoiseSVN > Delete).
8. Commit the change (right-click in folder > SVN Commit).

Worry about these steps only if you check your output in to Subversion as well:

9. Generate and then publish help to your hard drive (check out my post on making WebHelp and FlashHelp output work correctly with Subversion).
10. Delete the old file (right-click file > TortoiseSVN > Delete).
11. Commit the changes (right-click > SVN Commit).

As you’re developing a help system and updating content, it sometimes becomes necessary to rename a topic file. When you’re using both RoboHelp and Subversion, it’s easy to mess things up doing this. It’s important to rename the file in RH first so that all links, including in the TOC and index, stay up to date. But things have to be done correctly in Subversion too.

These steps go through the steps in general plus specific steps in parentheses for the TortoiseSVN client for Windows Explorer (currently version 1.6.10), which I use. The TortoiseSVN steps explain what to do in Windows Explorer.

› Continue reading…

I’ve expressed dissatisfaction in the past with the traditional tri-pane help format. I think it’s outdated and has gotten such a bad reputation with computer users that it’s too late to change that. So I think it’s time to find other ways to provide user assistance.

A few weeks ago, I got an email stating I was now being followed on Twitter by @helpburner. I thought this could be another technical writer, and I usually check the tweets of people who follow me anyway. Imagine my interest when Mike Stokes, the owner of this account, had tweets mentioning the beta test of a product called HelpBurner.

› Continue reading…

I don’t think online help is the wave of the future—it’s more the wave of the past—but I’m still always trying to keep my brain open to ideas for improving it.

I attended a meeting today with the folks I work with in a project portfolio. Our portfolio manager reviewed what the group accomplished in 2009 and showed us what’s coming up this year, including the goals the managers cooked up.

One of the developers demonstrated an application his team built for their customers to use in accessing content in a MarkLogic database. Of course, the application featured robust searching because of indexing and tagging.

This got me asking myself: What if online help could be configured to be context-sensitive in a different way than usual? What if, when the user launches the help system, instead of opening to some assigned help topic, it instead runs a preprogrammed search on keywords assigned to that topic? Then the results display in the help window, and the user can scan the results and choose where to start? Basically, can anticipatory search be done, and would it be helpful?

› Continue reading…

I recently held some informal usability testing for some changes to an online help system I was considering. Because I hadn’t done any testing on the original help, I incorporated some of that as well. Doing so pretty much confirmed that I was on the right track with the changes I wanted to make. The help as it stood wasn’t very usable.

All documentation can stand some usability testing. We technical communicators like to claim that we’re user focused and user advocates. I like to believe that myself. However, sometimes we can be more like developers than we want to admit. We do things our way, the way we think is best. We may have even proved in the past that what we’re doing is pretty user-friendly. But times—and users—change.

› Continue reading…

I conducted some context-sensitive online help usability testing with four users of a Web application. This post discusses the results (without getting overly academic in tone, I hope).

Objective

I wanted to find out whether and how quickly participants could find given pieces of information and answers to specific questions in two versions of a help system described in this post.

Specifically, context-sensitive topics in the first version have a screenshot giving an example of how the screen can be used, sometimes with numbers corresponding to annotations in the text below. The newer versions of extensive help topics had the screenshot hidden in a dropdown hotspot and details contained in dropdown hotspots instead of being annotated. Specifically, the hotspots were formatted as green, underlined text with a right double angle bracket afterward.

› Continue reading…

Documentation doesn’t need a full-blown usability test, lab with one-way mirror and all, but it should have something. That’s one thing I’ve been working on this week with a particular help system I described in my last post.

When doing usability testing on documentation, keep the following things in mind. (These apply to any type of usability testing, actually.)

1. The participant isn’t being tested—the documentation is. Make this clear to the participant. You may even want to put it as simply as, “You’re not being tested. I am.” You want to observe how a person interacts with the content. The participant will face no adverse consequences for not successfully completing a task.
2. Come up with scenarios and tasks where the context makes sense to the users. Similar to examples used in documentation, if the situations you present don’t make sense in the participant’s world, she’ll spend time getting confused or correcting you. Think through the context of the tasks you’re using to be sure it holds up.
3. The participant should speak out loud so you can record thoughts, feelings, and reactions. It’s okay in informal testing to ask, “What are you thinking right now?” or “Why did you choose that option?”
4. Any pause in movement of more than a couple of seconds means the user has to ponder what to do. That suggests a potential usability problem.
5. Put together follow-up questions to find out how the participant feels after interacting with the documentation. Of course, you’re looking for objective data and observations; however, one of the important things to find out is the impressions the participant comes away with regarding the documentation and the product. Those impressions could very well affect how much the person wants to have anything to do with your organization and its products.
6. It’s okay for the participant to give up. People do that. Explain this to the participant. Usability testing is about seeing whether people can complete tasks successfully most of the time (or ideally, all of the time). You may wonder whether telling the user that she can give up is somehow planting that idea in her mind. But if the person were on her own and trying to use the documentation, she would think of giving up just as quickly.