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

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

Guest post by Kristi Leach.

So, You Need a Book about Usability

A while back, I asked Karen Bachmann, a usability expert in our STC chapter, to recommend some books for our tech comm department. I was looking for a place to start with the topic. Without hesitation, she told me everyone should read Steve Krug’s Don’t Make Me Think.

So, I ordered both Krug’s books: Don’t Make Me Think and Rocket Surgery Made Easy. Rocket Surgery is an expansion on his explanation of how to do simple, cheap usability testing. It comes with great check lists and sample scripts that you can download, along with a free chapter of the book and recommendations on equipment.

Once I had read Don’t Make Me Think, I wanted to send recommendations to our developers. That seemed like an overwhelming undertaking, so instead, after reading Rocket Surgery, I decided to implement a testing schedule for our documentation, with the long-term goal of getting to test our products.

› Continue reading…

Bookmark It

Hide Sites

I knew from the email subject line that I wasn’t going to like what was in the message.

The subject contained the name of an application, then two frightening words: “help sheets.”

I’ve found that outside the tech comm profession, people tend to throw around terms like “help” and “tips” without really thinking about what they mean. That’s why I felt a bit of dread as I opened this particular email.

The Rogue Documents

Looking for feedback, the product manager had forwarded two Word documents from an instructor who teaches this particular application as part of a week-long training for office staff. The instructor had documented a couple of end-to-end processes that weren’t strung together like that in the help.

Let’s just say that these documents weren’t done by a professional tech writer. I didn’t even get down to giving feedback on a content level; a subject-matter expert did some of that. Instead, I was concerned that by giving these documents to the class members, we were providing an inconsistent and less-than-professional experience.

I was also concerned because these documents’ pages were numbered 35 through 41. So what else was there that we didn’t know about? How much effort was being duplicated? Since it’s my full-time job to create such materials, I would have preferred if the instructors let us know about the need and asked me to fill it. Frankly, it felt a bit threatening, as if I thought my job was in danger. I considered this “rogue,” or unofficial, documentation.

The Idea

I ignored this email until the next day. Then, however, I decided to change my stance. I realized this was an opportunity, not a slap in the face.

› 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

Still somewhat surprised that Vanessa, the project manager, had labeled him a major player in solving the customer’s problems, Henry projected his improved diagram onto the screen. Everyone looked at Vanessa.

“Henry, will you explain the diagram, and then we can go through each situation and find out whether the right things are happening.”

Henry hadn’t expected to guide the discussion, but he talked through the diagram. Then he began going through each relationship and explaining the effects of the relationship on the reports that the users were generating using the software.

As they went, the customer identified where things were happening correctly and where something needed to change. Vanessa kept track of action items, and since they uncovered a couple of inaccuracies, Henry took note of where he needed to make changes. Vanessa then asked Henry to create a version of the diagram that represented what should be happening in the software as if it already was. The development team could take that version and begin creating and assigning tasks.

When the meeting was over, Henry couldn’t help but experience some relief. The spotlight had been moved elsewhere. His original documentation on the software had contained a couple of errors, and he would fix them, of course. It was possible that the number of questions and problems coming back to the customer stemmed from those errors. But this possible communication problem had exposed a programming problem. And Henry, being the professional communicator on the team, had taken the task of communicating to the customer how the software currently worked, and doing it clearly enough that the customer could make informed decisions. So communication had been the first step to solving the programming problem.

› Continue reading…

Bookmark It

Hide Sites

Once again, Henry met with the project leadership; only this time, he was the star of the show. In the last meeting, he had taken the assignment to diagram the relationships that were currently possible to set between two types of objects in the software, as well as the downstream effects of those settings. He had to represent four criteria in a two-dimensional diagram but had a hard time thinking in four dimensions at first.

After some thought and experimenting, he accounted for all four types of variables by combining two of the criteria into one axis, putting the third across the other axis, and explaining the effects at the intersection of row and column. It didn’t look amazing, but it would do the job.

A little timid, Henry projected his laptop screen onto the conference room wall. He glanced around and saw a couple of confused looks.

› Continue reading…

Bookmark It

Hide Sites

Henry opened up a PDF on his laptop and went to page 27. The meeting continued around him as he scanned the text of the procedure he’d written 18 months before so he could verify some of the information that had been distributed.

“One way to look at this is that we want to prevent our customer from getting these phone calls all the time—or at all,” said Vanessa, the project manager. “What’s the first step?”

George, the business analyst, lifted a hand. “Well, since he keeps getting asked why people are or aren’t seeing this or that in the reports, I think it’s a data problem. We need to start there.”

“Or it’s a training problem,” said Melanie, the lead of the quality assurance team. She looked at Henry. “If there’s a data problem, maybe the users don’t understand how to set the data up correctly.”

› Continue reading…

Bookmark It

Hide Sites

The other day, I was talking to one of the interaction designers I work with, and he mentioned something that brought a little shame upon me. He had been talking to one of the application’s users when she pulled out a manual for the legacy application—contained in a binder, I think—and it had loads of handwritten notes in it. I realized that I had ignored one of my own suggestions when dealing with legacy apps. I had not looked at, let alone leveraged, any legacy documentation.

This is a fairly small project and is phase one of two. The user base isn’t large. When I started on the project, I figured I would just document the new system. Much of the work I’ve done over the last few years has to do with applications that replace legacy systems, and I think this time I may have just overlooked the legacy documentation because of the project’s relatively small size.

Even if I don’t end up using any of the legacy content, it’s a valuable exercise to see what’s there, what the users have been making use of. It’s even better to see what notes they’ve been writing in the margins so I know what kinds of information they find important.

The designer will send me the electronic copy of the old manual, which will be a good start. Next will be a trip to the users’ desks to see their own additions, perhaps what you could call the original wiki. Phase one of the project is nearly over, but I’ll have phase two in which to make any adjustments based on what I find out. It’s been a good reminder of what I ought to be doing when documenting applications that are replacing legacy apps.

Bookmark It

Hide Sites

A few weeks ago, I received an email from a reader who had performed a study about what Web site visitors believe a good online experience is. More on that in another post. But as a technical writer, when I am documenting software, the design bears as much on my experience as it does on any user. So I think about good application design quite a bit.

I once overheard a Web designer say something to the effect that “if an app is designed well, it doesn’t need help,” meaning a help system.

Say what?

› Continue reading…

Bookmark It

Hide Sites