I wonder if there’s a tech writer out there—in the software industry, anyway—who would argue that being involved in the design stages of a project is a bad thing.

This theme comes up time and again among our User Education team members. Yesterday, one of us gave a presentation to our community of practice about usable design, what makes something usable, and how tech writers can contribute. She suggested we come up with some metrics that help us demonstrate how our contribution to usable design increases user productivity and lowers cost.

As part of her illustration, she showed a chart about the more and more expensive it gets to fix a bug from the requirements stage through to the maintenance stage.

An idea came to mind, and I shared it with the team, that one of the things that we can use some hard numbers with is determining how many steps it takes to complete a task. The presenter had used an example to show how a process that she would have expected to take four steps instead took twelve. If we can analyze designs and determine how many steps it takes to complete associated tasks, we can tell the project team, “That’s going to be hard to explain. That process will take ten steps (or fourteen, or twenty). And when a user sees a procedure with that many steps, the first thought is ‘This is going to be hard,’ probably followed up with ‘I hope I do it right.’ Confidence goes into a nosedive.”

› Continue reading…

Bookmark It

Hide Sites

Many times when I think of surveys, I think of the Animaniacs cartoon with the ladies who asked the three Warner siblings, “Would you like to take a survey?” There followed many questions with every imaginable permutation based around George Wendt, movies, and bean-eating.

Recently I conducted an online survey on the training and help materials for System X, a Web-based app for office staff. I didn’t ask a single question about George Wendt or beans. My two main goals were:

1. Find out how good the training was that the respondents received in person
2. Learn how much the respondents use the training and help materials in the application and how effective the materials are

Basic Results

I ended up with sixteen questions, some of which were demographic. According to Qualtrics (the software I used), 497 people accessed the survey, and 420 people completed it. However, I found as I analyzed the results that some respondents skipped questions and didn’t really fill it out completely. Still, about 230 out of 340 worldwide offices were represented in the result set, and I’m happy with the relatively high response rate.

As a bit of background, we have an online help system and a training page for this app. The training page has links to role-based quick reference guides in PDF and video demos in Flash. The help is your typical old-school tripane WebHelp with index, search, and so on.

Here are some key findings (numbers taken from those who responded, not the overall 497 or 420):

• 42.7% were not aware of the quick reference guides
• 28.3% were aware of QRGs but never use them
• About 25% have used QRGs at least once
• Average effectiveness rating out of 1 to 7 is 4.11 (so just above moderate)
• About 85% print QRGs when they use them

› Continue reading…

Bookmark It

Hide Sites

Sometimes I get ideas about a problem I’m trying to solve once I’ve stopped actively thinking about it and have let it drift into the back of my mind. With Project Pinnacle, something escaped my attention until a few weeks after my visit to the pilot site.

Well, it didn’t entirely escape my notice, but its implications for documentation and training didn’t hit me immediately.

The thing I noticed while watching users try out my quick reference guides was that they tended to follow only the first few steps of the procedure. They would look at it long enough to get to the screen where they performed the task, and then they would try to do the rest without the guides.

One of the reasons for this is that they had to keep glancing between the monitor and the paper, which made it easy to lose their place. Trying to use a finger didn’t help much either because at some point they had to start typing.

A few weeks after my visit, I got an idea of maybe a true quick reference guide that would fit what they needed. Since they relied on the printed procedures only for navigation, why not just provide the navigation steps?

I put together a version of each guide that listed the steps with double angle brackets between each step. This condensed the existing material from about four pages for each guide down to under one page. I haven’t tried these versions out yet. The project manager wasn’t in favor of the version of the guides that have the screenshots with callouts because of the cost of keeping the screenshots current for all languages.

When I first reported to the project leadership about my visit to the pilot site, I pointed out that a way to improve our training of our audience and at the same time reduce documentation costs would be to provide more prompts in the application. I’m not trying to reduce my workload, but I believe that the more help you provide in the interface, the less help you have to maintain elsewhere. I know, not real profound, but it’s not something very many product designers think about.

Since then, I’ve provided prompts and descriptions for a number of application screens and features. We’ve seen a direct impact of this as we’ve worked on the training video scripts. We want to keep the verbal explanations simple and let the features be demonstrated so that we don’t have to rerecord the audio if features change. The fact that we’re including help in the interface helps us do this because we can leave much of the explanation to the application itself.

Image credit: Salvatore Vuono, freedigitalphotos.net

Bookmark It

Hide Sites

Last week I visited the pilot location for Project Pinnacle. My focus was to see how well my first-draft quick reference guides worked, but I spent some time training.

The office staff tended to want to ask me how to do things and be walked through it, but I took those times to ask them to test out the instructions for me. However, on one occasion, I had to guide a brand-new user through a somewhat complicated scheduling procedure while she was on the phone with the person setting up the appointment. I figured it would be better to help her through that one because she’d feel enough pressure from trying to do it right and in a timely manner.

In addition to notes on improvements to make to the guides, I kept other notes. The rundown:

• 5 tasks to add to the guides
• 14 other changes needed to the guides
• 20 feature or change requests
• 10 bugs
• 14 miscellaneous items that were questions, observations, or usability problems

› Continue reading…

Bookmark It

Hide Sites

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 my initial conversation with the manager of Project Pinnacle, we decided on a set of role-based quick reference guides as the documentation for the application.

I ended up with about five weeks to complete these guides in the midst of other projects. After a demo of the application given by the lead tester, I sent the manager an outline of each guide. He didn’t get back to me right away, so I started writing the guides while using a test version of the application.

The guides’ structure was pretty simple. On the first page, I included a screenshot with callouts that explain the navigation structure of the application: header, subheader, tabs, links, buttons, and so on. The hope is that this would reduce the amount of instructions needed by covering the basics together. After basic navigation, I covered the main tasks for the role in question.

› Continue reading…

Bookmark It

Hide Sites

That word has reared its ugly head again.

A recent post by Ellis Pratt on the Cherryleaf blog discussed David Black’s claim at the TCUK 2010 conference that someday, end-user documentation won’t be needed. Ellis says:

Although he felt no-one but Technical Authors had the answers to how to understand complexity and failure, he believed that products would become so intuitive, and people would be so technically adept, that there would be no need in the future for end-user documentation.

Other than the fact that I think it’s a bit tacky to respond to an invitation to speak at a tech comm conference by telling all the attendees they’ll be obsolete in a few years, I have a problem with this fallacy that anything, especially technical in nature, is intuitive. I’ve heard the word intuitive in this context so often that I’ve come to almost despise it.

It’s something of a cliche to consult the dictionary when trying to prove a point, but in this case, it’s highly called for. Dictionary.com says, and I quote, intuitive is “perceiving by intuition, as a person or the mind.” Well, nothing like using the word to define the word, so here’s one of the definitions of intuition: “direct perception of truth, fact, etc., independent of any reasoning process; immediate apprehension.” The next few definitions are similar. Then we get the definitions according to the school of philosophy:

a. an immediate cognition of an object not inferred or determined by a previous cognition of the same object.
b. any object or truth so discerned.
c. pure, untaught, noninferential knowledge.

Note that part of this definition are the concepts of no previous knowledge and being untaught. The other definitions hint at these concepts, but the philosophy definition calls them out specifically.

I continue to argue that very little in life is truly intuitive. The idea that we can fabricate and invent things that are in some way intuitive is a myth. I’ve had this cemented in my mind even more through recent experience.

› Continue reading…

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