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

Over the last few months, the User Education Team has developed a content model and a supporting style guide. Our evaluation of various documentation authoring tools a few months ago resulted in our choosing Author-it—a tool none of us was familiar with.

In our discussions about our content model, or how our information is structured, sometimes we kept drifting into talking about what Author-it would allow us to do. It was an easy line to cross. The way you approach reuse and other considerations can change based on what tool you use.

But overall, the optimal way to structure information isn’t dependent on a tool. That’s probably why our team lead kept steering us away from thinking about whether aspects of our authoring approach and information architecture would be supported in Author-it. There were parts of our discussions that blurred the lines—we would sound like we were talking about the tool, but we really weren’t.

Such discussions highlight what I’ll refer to as the core component of technical communication.

That component is the heart of the term technical communication—that is, communication.

The secondary part of that term, technical, refers to the subject matter we are communicating about. But it could also refer to the method we choose to author, organize, and deliver the content, which these days rests in technology.

Technology changes. Communication channels and content delivery mechanisms change. We have Author-it today, but something more fitting for our organization and our needs may come along in a few years. DITA has spread through much of the tech comm space, but who’s to say something more effective won’t come along in the future, or that DITA won’t evolve (see what I did there) into something better?

Yes, the technology changes, but the core principles of communication don’t.

› 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

Not that I’m the most stylish guy, but I’ve been working on a short style guide for our team. Our organization has a style guide that relies heavily on the Merriam-Webster dictionary and the Chicago Manual of Style, but it gives little attention to content regarding technology. To this point, the team has used the Microsoft style guide (third edition) as well, but it has some style specifications in it that seem pretty outdated—and rightly so, since it was published in 2003 or 2004.

The objective for our style guide is to highlight the most important considerations so they’re together in the same place. That way, when we have a new member of our team or another contributor, it’s not a huge chore to review the team style guide and get up to speed.

It was with this in the back of my mind that I went to the Society for Technical Communication’s (STC) yearly conference a couple of weeks ago. I attended some sessions that had to do with writing for localization and for accessibility. In her presentation, “DUH: Diverse. Understandable. Human,” Char James-Tanny talked about inclusion being a better word than accessibility. Her presentation came close to what I had begun thinking about.

› 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

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

I just started on a new project this month. Taking the lead from Karen Mulholland‘s reporting on her Tribal Knowledge Project, I’m going to blog about how it goes.

In order to protect the innocent, or the guilty as the case may be, I’ll call it “Project Pinnacle.”

Tom, one of my User Education colleagues, was approached by a project manager he had worked with before to work on Project Pinnacle, but he didn’t have the bandwidth to take on a new documentation project. Tom asked if I could do it, so I asked him about the timeline and what deliverables were needed.

He told me a bit about it, and I decided I could take on the project. Tom forwarded me some information, including a link to a test version of the Pinnacle application and test credentials. When he let the PM know that I was picking up the project, Tom sent me an email explaining what he knew about the project to that point. Pinnacle would be used at various locations worldwide for organizing workers and their shifts and also scheduling visitors.

Tom and the PM had talked about making a set of role-based quick reference guides. He said that the application didn’t have a help link and needed one. I took this to mean that online help was an expected deliverable for the project, and I was a bit uneasy about that, especially since Tom indicated that the timeline was pretty short.

I decided that rather than jump in and start developing material, I needed to talk to the PM. I had a hard time getting a hold of him; I tried instant messaging, phone calls, and even stopping by his desk. In the meantime, the quality assurance lead had offered to give me a demo of the application, so I took him up on that.

Fortunately, Tom sits near the PM and let him know I was looking for him. He IMed me to find a good time and then called me on the phone.

My main questions were about schedule and scope, since I needed to make sure we would have the same expectations.

The PM told me that Pinnacle would be piloted in Twin Falls, Idaho five or six weeks out. He was still working out details. To my excitement, he asked if I was interested in joining him and the product manager the last two days of the week, which are the days of the heaviest traffic in that location, to observe users and see how they like to get help.

Heck yeah I’m interested, since usability is one of my interests and I also want to test out the guides I will have created by that time.

I asked about the deliverables for this pilot. We agreed on a set of quick reference guides, but I expressed my reluctance to do an online help file because I didn’t think the user demographic prefers that (and I’m not sure what demographic does prefer online help files). I was relieved when the PM said that he didn’t think a help system is a good fit for this project, either. Our users will mainly be people between the ages of 55 and 75 or 80.

So at least for the first stage, I’ll be creating four quick reference guides to be ready, at least in draft form, for the pilot in a few weeks. I’m looking forward to watching the users and seeing how well the guides measure up. It will be disappointing if what I put together doesn’t prove to be what they want and need, but I’d rather go on-site and find that out rather than prepare and distribute materials that don’t do the job.

I would have liked to be brought onto the project earlier so I had more time to work in. This is one of the reasons I want to write about how things go—it will be a way to reflect on and analyze what I’m doing and see if it’s working. Come along for the ride and feel free to offer advice on the way.

Bookmark It

Hide Sites

Recently, I had some technical problems with this blog that seemed to result from a category excluder plugin. Somehow I ended up with a bunch of duplicated categories with one post assigned to each one. This was causing links to be broken and posts to somehow show up as uncategorized. Tags had also been removed.

After trying a couple of fixes to the broken links and phantom categories, I was afraid that I would have to delete all my categories and go through all 300+ posts, reassigning categories and tags. Once I found the real problem, I took the time to correctly assign posts to their original categories and delete the duplicates.

Strangely, the prospect of coming up with a new list of categories and tags and then assigning the applicable ones to each post was somewhat inviting.

Why?

If You Don’t Know Where You’re Going . . .

I realized some time ago that the categorization and tagging of my posts was pretty haphazard. I didn’t have a strategy or information architecture for my blog. If I wrote a post on something that didn’t fit in any existing category, I created a new one. If it related closely enough to an existing category that creating a new one didn’t make sense, I renamed the category (if WordPress let me) to include the new topic, such as “Web Design & CSS.” I came up with tags almost in a vacuum because I didn’t—and still don’t—have the patience to wait for WordPress’s autocomplete feature to load while I’m typing tags.

The architecture of my blog was like an untended garden, and creating an organization for my posts from scratch was tempting to me.

› Continue reading…

Bookmark It

Hide Sites

One of my fellow members of the Intermountain Chapter of STC is a major proponent of tech writers having project management skills. Planning is one of these skills.

I’ve thought for years that I’m not interested in becoming a project manager because the only writing they do is project plans. That kind of writing has held no appeal for me, and that’s probably why I’ve never seriously considered writing documentation plans before now.

Tom Johnson recently wrote about how the user education team in our organization is introducing a user education plan as part of the standard planning process for projects. He explains that he has come to support having this plan to fill out mainly because it will help him manage his time so he won’t be overwhelmed by work for various projects and then become unable to deliver quality products.

For me, the attraction of a user education planning document is to speak project managers’ language. They think in terms of budget, milestones, deadlines, requirements, and risks. A good user education or documentation plan will address these areas.

› Continue reading…

Bookmark It

Hide Sites