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

Eleven months ago—eleven months—Marc Achtelig emailed me about the resources for technical communicators on his site, indoition.com. I lost track of the email, so I publicly apologize to Marc for my lack of organizational skills when it comes to email. Thanks for your patience.

A few of my fellow tech comm bloggers posted back then about Marc’s site, so maybe it turned out to be a good thing that I screwed up, because Marc has updated his site. I took a look at his help authoring tool list, and I couldn’t believe how many there are. I hadn’t heard of most of these. But if you’re trying to put the strategy and the audience’s needs before deciding on the tool (in which case I salute you for putting things in their proper order), then Marc’s list is a good place to come to find a tool that fits the situation. Before you start, click Show/Hide Details to the right of the heading. That collapses everything so you can browse the basic types first.

The Choosing a Help Authoring Tool page gives some additional points to consider while you’re deciding on your tool, but these items are focused more on the author’s experience.

The HAT page isn’t the only page that lists software, though. There’s an entire list of software types or focuses in the nav column under “Useful Software.”

The quality checklist has some good questions to ask yourself while writing or editing. I particularly like the questions under “Tone, unambiguousness.”

I encourage you to take a look at Marc’s site. He’s done a thorough job of providing useful information for technical communicators.

Note and disclosure: This post is intended as a help for technical communicators and not as an advertisement of Indoition’s commercial services. Marc did add a link to this blog under Useful Websites > UA (User Assistance) and Technical Writing at some point (thanks!), which he offered to do in exchange for a post about his site.

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

Once upon a time, a curious little guy named Doubt went to visit his friend. After getting there, Doubt went looking for the kitchen to get a snack.

As he walked down the hallway, he found two doors. The first, which had a plaque that read “Don’t,” seemed after a bit of testing to be locked. The second had a plaque reading “Shouldn’t,” and it stood slightly ajar. Doubt slipped through the doorway and found himself in a small chamber. And it wasn’t the kitchen.

What’s the moral of the story?

I’m working on a little style guide for direct and concise technical writing. One pointer is to avoid the use of should or shouldn’t when what you really mean is do or don’t. Saying something like “shouldn’t” makes it sound optional. In other words, shouldn’t leaves a little room for doubt. Don’t, well, doesn’t. (But notice that Doubt tested the lock on the Don’t door anyway.)

Bookmark It

Hide Sites