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.

Tri-pane help appears to have been invented as a way to provide booklike documentation—that is to say, linear documentation. The table of contents, index, glossary are all carry-overs from when all documentation was in hard-copy manuals. While a book’s material isn’t necessarily linear, it still reflects linear thinking.

The Web Offers More

Ginny Redish’s book argues that because the Web is a different medium and holds different possibilities, we shouldn’t hold ourselves to organizing Web content in the same way we organize book content.

Tri-pane help is a pseudo-website; it has a header or toolbar of some kind and a left pane for left-hand navigation. Help authoring tools make it easy to assemble tables of contents, indexes, and glossaries, but they’re only making it easy to perpetuate the linear thinking of books and to not take advantage of what current Web technology has to offer.

Letting Go of the Words talks about performing audience research and then setting up the home page, pathway pages, and information pages in a targeted way. Navigation deliberately and clearly guides users from start to finish, each page and link letting them know they’re on the right track.

You don’t have to set up a help system’s TOC just like you would a book’s. You could organize it in some other way than introduction, chapters, appendix, and so on. But how often do we take the time to do the kind of research we need to in order to make a table of contents even partially effective?

One of the limitations of a TOC is that you can display only topic titles. If you set up pathway pages like Redish describes, you can give the reader more guidance. A risk you take with TOCs is that as the user doesn’t find what he wants, he expands more and more books or folders, and he ends up with an overwhelming list of topics. Instead of holding his hand and leading him along, you’ve paralyzed and frustrated him.

In my experience, help authoring tools don’t lend themselves to dynamic Web outputs that allow you set up this kind of guided experience. You could do it, but it’s not supported well out of the box.

What about Search?

I was talking with my team lead a few days ago about this. He brought up search. Tri-pane help offers search, so how is a website like I’m describing any better?

I’ve got a few responses to this.

• Not everyone searches. Many people do follow links in menus.
• Multiple pathways increase the likelihood that people will find what they want.
• The search function in tri-pane help usually stinks.

I’m a fan of search. If search is well done, it can quickly take users to what they want. If that’s the route they choose. But it shouldn’t be the only way to look, or else we run the risk of the answer to the user’s question being too far down the results list to be found.

Wrap-Up

I think creating tri-pane help tends to lull technical writers into going through the motions. “Okay, I’ve got search, a table of contents with all my topics listed and organized, and as many index keywords as I could come up with. My help is helpful.” We sometimes fool ourselves into thinking that because these boxes are checked, we’ve done a good job at providing quality content and structure.

It would be better for help authoring tools to provide more flexibility so we’re forced to put in the research and thought required for useful content and architecture.

My hope is that in our search for the optimal tool, we find one that doesn’t force into creating tri-pane help and instead allows more flexibility and visual appeal.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. RoboHelp Packager for AIR Critique, Part 2
2. Help Authoring Woes: Index As You Go
3. Time for Online Help to Get a New Wardrobe
4. Could Technical Communication Be Entertaining?
5. Anticipatory Search in Context-Sensitive Help

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.

Setup Guide: Document about the same size as a short guide but that is focused on setup tasks. Used when there is too much information for a quick-start guide.

Comprehensive Guide: A full document with fairly complete information about how to complete tasks with the product. Includes reference information and maybe troubleshooting information. Used when a user will perform a wide range of actions with the product, product uses a specific set of terms, and/or product is complex.

Training Guide: A document about the size of a short guide with a focus on teaching the user how to complete core tasks. Concepts build on each other. Examples and exercises are included. Used when someone needs to be trained to use a product by using the product.

Microsoft HTML Help System: A set of HTML files with a table of contents, glossary, and index, all running within a single file (.chm). Installed with software. Used with software installed on the computer hard drive and the user may not have an Internet connection. Contains instructions on completing tasks. May contain context-sensitive topics, reference information, and troubleshooting information.

WebHelp System (or variants): A set of HTML files with a table of contents, glossary, and index. Hosted on a server. Contains instructions on completing tasks. May contain context-sensitive topics, reference information, and troubleshooting information. Used when an Internet connection is common for users.

Knowledgebase: A set of HTML files that contain reference and troubleshooting information.

Web-based Help or Support Site: A dynamic, searchable website containing a variety of topics. Users can comment on topics and browse topics by tag. Allows integration with social media.

Demonstration Video: A recording of the use of a product, usually software, to show how to complete certain tasks. May be used if no test version of the product is available, and practicing with the product isn’t an option. May include voiceover or text captions.

Overview Video: A short introduction to a product that highlights key features. Doesn’t show how to complete specific tasks. Used to give users a brief exposure before they begin using the product or even as an advertisement.

Static Simulation: A video that relies on actions from the user to move forward, typically in what appears to be software. The user must follow a particular path to complete the task, and choices and exploration is limited. May be used as a scripted demonstration so that the demonstration always shows the same functions (and always works).

Tutorial: A blend of demonstration and simulation. Users are shown how to complete a task and then are given the opportunity to try it out.

Wiki: A set of webpages that are editable by any user with an account on the platform. Users can also add and remove pages. Pages have revision histories, and changes may be subject to approval by an administrator. Used when a product has an active community surrounding it whose members are interested in contributing information about the product.

Blog: A website or webpage that is updated regularly, giving updates about a product. Usually somewhat informal in tone. Used when a product’s users want to receive information about a product in between releases.

Release Notes: Short documents, such as a readme file or PDF, that lists the changes in a major release, update, or patch to software.

Inline Help: Text on websites or in applications added to elements to provide some context or examples for using the elements. Used when users may need minimal information to successfully navigate and complete a task.

Embedded Help: Text on websites or in applications that is contained in boxes, sidebars, or modal windows and explains elements in more detail than inline help. Used when further information is required outside the main flow of the webpage or screen.

Tooltip Help: Text on websites or in applications that appears when the user places the mouse pointer over an element for a few seconds. Used when brief hints or reminders are needed and real estate is scarce.

Autocomplete: A text field that provides a drop-down list of options matching typed characters as the user types. Used when only certain options are available, but there are too many to include in a drop-down box, or to provide recommendations.

What would you add? What information have I forgotten from the items here? I’ll update this list based on your comments.

Update: Added release notes, tooltip help, and autocomplete. I wouldn’t have thought of autocomplete features as user assistance, but after it was suggested and I thought about it, I agree. Autocomplete can give guidance so the user doesn’t enter data that the software can’t handle.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Findings from an Online Help Usability Test
2. Offering a Menu of Tech Comm Deliverables
3. Why a Transition from Tech Comm to Usability Makes Sense
4. A Way to Get Technical Writing Practice
5. Get Passionate about Tech Comm

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

Related posts (auto-generated):

1. Tech Tip: Checking WebHelp/FlashHelp Output Files in to Subversion
2. FlashHelp Tech Tip: Removing IE's "Click to activate and use this control" Message
3. RoboHelp Packager for AIR Critique, Part 2
4. RoboHelp Packager for AIR Critique, Part 1
5. Changing a Topic File Name in RoboHelp and Subversion

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

Related posts (auto-generated):

1. User Assistance Embedded in the Interface
2. Empathetic User Assistance
3. Clear, Common Language Leads to User Success
4. Spending Time with Users to Learn How They Want Assistance
5. Knowing How Much Visual Assistance Is Too Much or Too Little

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.

Developing Organization in a Vacuum May Be Impossible

The order of the cards can affect how things are categorized. If participants went a long time without seeing something related, once they did see something related, they may have forgotten they saw that first one. It reminded me of playing Memory. Further, related to the previous point, titles are extremely important partially because people see relationships between topics based on keywords in the titles.

I don’t think organization can happen in a vacuum. Participants organized their cards based on what they had seen before and what was in front of them. They started developing subcategories only when the number of cards they had looked at grew and they started seeing patterns.

I gave each group the same cards, but each stack was shuffled, so the order was different for each group. This is one factor that affected how they may have organized the cards.

Considerations: Basically, participants were sorting a topic based on its context with other topics. When someone is looking for information, they may or may not look based on its relationship to other information. For example, doing a text search is looking without context. But browsing through categories, tags, or other kinds of lists provides some context, and the topics’ relationships become important.

Tagging Would Accommodate Topics’ Multiple Themes

Tagging in a content repository would be useful because of the multiple categories a single topic can go in. For example, if you have a topic called “Making a Payment to a Vendor,” does that go with the information on payments or with the topics about vendors? Having a way to tag this topic with both “payment” and “vendor,” as well as “finances,” would be useful.

People Are Convinced Their Way Is Correct

In one of the groups, two participants disagreed with the third about where something should go. There was a somewhat heated discussion about it, and it basically came down to the winner being the most stubborn person. I saw other times where one participant would decide a card went in a certain place, and I saw nonverbal communication from the others that suggested they disagreed but didn’t want to argue.

People have their opinions on where they think things go in a set, which explains why they get frustrated if information isn’t located where they expect. Many times, when we’re looking for information, we have little patience and consider few alternatives to our preferred path.

It’s Hard to Be Objective and Quiet

As I watched, sometimes I wanted to speak up. It was hard to be objective and not think, “Why don’t you put that with those?” or “Hey, you put the other cards on that subject over there.” I mentioned the Memory game. When participants were looking for something they put down earlier so they could put another card with it, I knew right where they put it and wanted to point it out.

But I kept my mouth shut. I might skew the results that way. Or would I? I wondered whether that was really the case.

Considerations: If I help them find the card they’re looking for, am I contributing to their choices? Or am I skewing the results because I’m not waiting to see what they do when they can’t find something in their own organization of topics? I don’t have an answer for this one.

Wrap-up

I saw some patterns emerge from these sessions, which is helpful. But some topics ended up in a different category with each group.

The biggest consideration for these exercises is that they were all local people, though not all from Utah originally. It at least brought a way of looking at things in the culture of the United States, and I don’t have input from people in other countries at this point. This likely provides a narrow view, but I wanted to start somewhere and get other people’s ideas on how to organize the information.

Photo credit: clarita, morgueFile.com

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Write Self-Contained Titles to Preserve Context
2. Wishing I Could Start Over
3. Findings from an Online Help Usability Test
4. A Shift in My Context-Sensitive Help Approach
5. Results of a Team Design Review: A Different Context-Sensitive Help Structure

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

Related posts (auto-generated):

1. Changing a Topic File Name in RoboHelp and Subversion
2. Tech Tip: Checking WebHelp/FlashHelp Output Files in to Subversion
3. The Case of the Missing Help Topics; or, Version Control Comes Through
4. FlashHelp Tech Tip: Fixing the "Flash Player has stopped a potentially unsafe operation" Problem
5. Well-Phrased Links Help Both Users and Technical Communicators

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, right-click the topic, and click Properties.
3. On the General tab, change the file name.
4. Click OK.
5. Add the new named file to the repository (right-click > TortoiseSVN > Add).
6. Commit the new file (right-click > SVN Commit).
7. Update the folder containing the file to pull the old version of the file back to your hard drive (right-click in folder > SVN Update).
8. Delete the old version of the file from the repository (right-click file > TortoiseSVN > Delete).
9. Commit the change (right-click in folder > SVN Commit).
10. Update the file’s map ID if needed by deleting the old reference and then adding the new file.

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

11. Generate and then publish help to your hard drive (check out my post on making WebHelp and FlashHelp output work correctly with Subversion).
12. Add the file with the new name to the repository (right-click > TortoiseSVN > Add).
13. Delete the file with the old name from the repository (right-click file > TortoiseSVN > Delete).
14. Commit the changes (right-click > SVN Commit).

Note: If you’re using Tortoise SVN on Windows 7 and run into a “can’t move” error in Tortoise, see the solution at http://schleichermann.wordpress.com/2009/12/09/svn-tortoisesvn-cant-move-the-file-or-directory-is-corrupted-and-unreadable-windows-7/. The comment from Tom on Feb. 16 2010 is especially helpful.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Tech Tip: Checking WebHelp/FlashHelp Output Files in to Subversion
2. The Case of the Missing Help Topics; or, Version Control Comes Through
3. Tech Tip: Click-and-Drag Image Import
4. Quick-Start Guides Require a Minimalist Mindset
5. FlashHelp Tech Tip: Removing IE's "Click to activate and use this control" Message

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.

The HelpBurner blog entry from May 13th says:

HelpBurner is a new way for web designers and developers to create project documentation, visual how-to’s, tutorials and support material… and we guarantee it will take you at least 50% less time, plus the help created will look beautiful!

And later on:

We think it redefines how help, user guides, tutorials etc are created and more importantly it makes help easy to use and empowering for your users (and did we mention pretty). This can only be a great new step for us all and lead to happier customers and more expert users of our products.

Strong claims of course, and the HelpBurner team is working to meet them. HelpBurner, which appears to be a Silverlight application, is currently in beta, and you can download it by visiting the blog post I linked to above.

I started out a little wary because the initial audience is advertised to be Web developers and designers rather than technical communicators. HelpBurner has promising features, though. Possibly my favorite is the ability to publish in an HTML format that looks like a website instead of tri-pane help. The authoring interface is simple and reminds me a bit of WordPress. My biggest request at this point is to be able to define and apply styles instead of just local formatting, which is currently all the topic editor offers.

If you create user assistance, I encourage you to try HelpBurner out and provide feedback. Mike Stokes, a company representative, is very responsive. I’m not sure when the full release will be, but now’s a great time to try HelpBurner and help make it what you want in a help authoring tool.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Call for Web 2.0–Friendly Authoring Tools
2. Help Authoring Woes: Index As You Go
3. Five Skills for Managing Documentation Projects in an Agile Environment
4. Styles in Inches and Points Improve RH-to-Word Output

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?

One possible downfall of this is that instead of being presented with some content, increasing the chance that the user won’t have to click around to find what he wants, some extra clicks are in fact required before finding answers. But many people are accustomed to search engines, where answers aren’t presented anyway. The user has to search first.

Some may say, “Isn’t that what an index is for? Essentially a keyword-based search?” I don’t think so. Indexes are something of a relic, a leftover from the days when the only ways to find information in a manual were the table of contents in the front and the index in the back. Further, online help indexes refer to topics, but they don’t give context. A good search engine does provide context in the results so the user can sift out irrelevance before clicking.

It would be interesting to try out something like this and then test it with users. Software like the Adobe Creative Suite opens its help to a search page, but of course you have to perform a search. The specific software you’re using doesn’t know which feature you want information about. I’m probably thinking more about Web apps, where you’re looking at a specific screen, so I imagine you could pass some keywords to the help and run a search.

If anyone is already doing something like this, I’d like to hear how it’s going.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. A Shift in My Context-Sensitive Help Approach
2. Help Authoring Woes: Index As You Go
3. Results of a Team Design Review: A Different Context-Sensitive Help Structure
4. Write Self-Contained Titles to Preserve Context
5. Usability and Maintainability: Navigable Information

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.

Most of the big trends in technical communication have to do with the information developer’s side of things: DITA, content management systems, structured authoring, single sourcing…. An emerging discussion of collaborative authoring between technical writers, SMEs, and other team members is moving toward what I think we should focus more on, which is how the users get their information. Of course, wikis have been a big topic lately, but we don’t talk about changing how users get answers much beyond that.

In my opinion, this usual focus on information developer processes is the reason why, as a whole, we’re still using things like FrameMaker and help authoring tools. The deliverables that come from these tools generally don’t reflect how people look for information. If we make a big enough fuss about what we really want, maybe tech comm vendors would respond and give us platforms like WordPress or wikis that you don’t have to be a genius to launch but allow for collaboration and customization.

Whatever platform you choose to deliver on, ultimately, usability should be a big concern. Documentation that’s not usable will not encourage people to use it, and we regularly return to the question of how to draw people into the docs to begin with. Even those who dare to use the docs will flee when they encounter difficulty getting answers.

Possibly because I’ve been thinking about usability lately, I signed up for the Usability and User Experience Special Interest Group (UUX SIG). I used to belong to the Instructional Design and Learning SIG, but unfortunately, I don’t do enough instructional design to get as much out of it as I otherwise could. We’ll see how it goes with the UUX SIG this year.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Six Things to Remember in Your Documentation Usability Testing
2. Some Observations from Documentation Usability Testing
3. Where Usability and Documentation Meet
4. Usability and Maintainability Not So Incompatible
5. Usability and Maintainability: Navigable Information