I’ve been reading Ginny Redish’s book, Letting Go of the Words: Writing Web Content That Works. It was a bit slow at first because the early material is pretty basic. And I came into it with the preconception that it wouldn’t apply much to documentation, since we write help systems and manuals.

In light of our team’s search for the tool that best meets a set of specific requirements, I’ve decided that Redish’s book has everything to do with what I do—or what I should be doing.

My Beef with Tri-pane Help

If you’ve been reading this blog for a while, it’s no secret to you that I’m not a big fan of tri-pane help. I think it’s dated and is associated in people’s minds with unhelpfulness.

But in our search for a tool that will give us a more robust Web output, I’ve discovered the main reason I don’t like tri-pane help.

› Continue reading…

Bookmark It

Hide Sites

In our quest to get more decision-making weight in the organization, the User Education team is putting together a set of standard practices. You may wonder why we don’t already have these. To put it succinctly, we still have to carve out our place in the IT department’s project lifecycle so that at least most projects have a user education component to them. Since there have been only a few of us, we’ve operated mostly by our own judgment, each person doing what he judged appropriate for each project.

We’ve come to realize that if we want our department to take us seriously and give us the place we want, we need to be equipped to justify the decisions we make on what user education products are right for any given project. One of the things I’d like to see happen in our team is to develop a menu of products, each with a specific definition and an explanation of the situation(s) in which we would recommend that product.

I’ve taken a first shot at this. I’d like your help to flesh this list out, the descriptions, and the reasons you’d use each one. In the comments, please let me know what I’ve left out.

Quick Reference Guide: One-to-eight-page guide that contains reference information, repeatable tasks, or some combination of these. Used when users have small number of tasks or will frequently need to refer to charts, tabular data, and so on.

Quick-Start Guide: One or two sheets that explain the steps for setting something up. Could also provide a set of most common tasks. A throw-away document. Focus may lean toward one-time training.

Short Guide: Thirty-to-forty-page document that provides task steps and reference information. Used when there is too much information for a quick reference guide.

› Continue reading…

Bookmark It

Hide Sites

RoboHelp’s WebHelp skins include a mini nav bar in the left pane. It holds forward and back buttons for browse sequences, a sync TOC button, and a button for hiding the pane.

If you’re like me, you don’t use browse sequences, and you set the TOC to sync automatically. As a result, the only button there is the hide (“X”) button, so it looks like the following image:

In this situation, the mini nav bar is mostly a waste of space. If you want to save some space by getting rid of it, here’s how to do so:

1. Open your .skn file.
2. Find and comment out both instances of the following:

<frame name="MiniBar Pane" marginwidth="-1" scrolling="no" id="6" />

3. Find both instances of what looks like the following:

<frameset rows="48,*" >

and change them to:

<frameset rows="100%" >

4. Save the .skn file.
5. Generate and view your WebHelp.

One of the nice things about doing this is your skin file is static, so it will apply these changes every time you generate your WebHelp output.

Note: This is how it works in RH7. If no changes were made in the .skn file for WebHelp in RH8, it should work there too.

Bookmark It

Hide Sites

I have a crackpot idea for presenting user assistance in software or on websites. Okay, maybe it’s not so far out there, but I haven’t seen this done anywhere that I can recall.

Like a lot of ideas, I was probably thinking about something else when this occurred to me. But I’ve got this picture of a div that slides or pops out in the interface when the user wants to see it to get more information. This pane could appear to one side or the bottom of the main section of the page.

Here are a couple of mockups. These are not to scale.

Help appearing to one side

Help appearing at the bottom

The advantages of this approach is that the user doesn’t have to see help unless he or she wants to, and it’s right there in the same window, not covering up anything, so you don’t have to switch back and forth between windows.

Disadvantages are the limited real estate for content and the amount that this may cut into the site or application’s usable space.

One of the main things I like about an approach like this is that I believe user assistance ought to be designed into the interface. It shouldn’t be something added at the last minute like you were deciding what hat to wear today before leaving the house. It’s part of the user experience, so it should be part of the user experience design—with input from the technical communicator, of course.

What do you think? Have you seen this kind of approach anywhere?

Bookmark It

Hide Sites

No, not that kind of cards.

As part of a continuous effort to improve a Web application help system I maintain, I conducted four card-sorting exercises to help me better organize the topics that aren’t context-sensitive but are either task-based or conceptual. I had nearly a hundred cards for each group. I had them go through the stack and organize things as they went and then do a look-over at the end and make changes if they wanted. They did this within 90 minutes.

To give credit where it’s due, I started thinking about this because of the presentation that Rachel Peters, Yina Li, and Will Sansbury gave at the 2010 STC Summit. And I based my exercises on the “definitive guide” by Donna Spencer and Todd Warfel on Boxes and Arrows. (I ended up with only four groups instead of five, but I left it at that because of the difficulty I encountered in getting the kinds of participants I was looking for.)

Here are some lessons I learned as I conducted these sessions, in no particular order. Some have to do with information architecture, and others have to do with conducting card sorting. I’ll also provide additional considerations that affect some of these conclusions.

Shallow Organization Is Preferred

Part of the exercise was for the participants to organize things the way they wanted and come up with their own category titles. My participants usually came up with only two levels. One group had a third level of organization in one category. This suggests that people naturally don’t categorize things more deeply than two or three levels because they may start getting lost.

Considerations: This may have been a result of the fact that I had only about 100 cards. If I had 1000, people may have felt a greater need to create more levels of organization. But with the cards I provided, more than two levels was certainly possible.

Title Is More Important Than Format

Part of what I was trying to find out is whether participants would consider the format of the information when searching for it. I have HTML topics, Flash video demonstrations, and PDF quick reference guides. I indicated with a small notation on the cards which format that topic is in: HTML, video, or PDF. Participants tended to ignore that notation (even though I explained it during the briefing) and sort things based on the title. This suggests people may think more about the topic title than the format when mentally organizing information.

The importance of titles was reinforced when participants didn’t know what a topic meant and I had to explain it if they were completely stumped. I determined that out of 96 topics, 27 needed changes to their titles. That’s almost one third. Identifying confusing titles was a great side benefit of these exercises.

Considerations: All index cards look the same, so it may be hard to think of the topics being in a different format. Some people would prefer a video and may want to browse the available videos instead of browsing by topic.

› Continue reading…

Bookmark It

Hide Sites

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

Bookmark It

Hide Sites

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…

Bookmark It

Hide Sites

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…

Bookmark It

Hide Sites

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…

Bookmark It

Hide Sites

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…

Bookmark It

Hide Sites