When getting a recent set of release notes ready, I sent them to the product manager for feedback. He emailed back and pointed out the concepts we needed to emphasize with a change we were making. I struggled to work them back in to my copy without making it more than people would read.

I decided I needed to take a step back and start over. I took some quick steps that helped me produce a much clearer and stronger message about the change being made:

1. Open a blank document.
2. Write in as brief sentences as possible the concepts that you need to get across. Boil the message down to its essential parts.
3. Revise minimally.

› 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

In the project portfolio where I work, we have several applications in maintenance mode. A number of developers and testers, some previously assigned to dev projects and others relatively new, may work on bugs from any application at any time, and most aren’t familiar with the applications yet.

My cubicle is next to that of Matt, one of the testers. One day he was trying to follow instructions in some test cases and hit a wall because of lack of detail. He called over Nathan, another tester in a neighboring cube. They launched into a discussion of how much detail should be included in test cases.

Matt’s problem was steps that assumed prior knowledge. It would be a general step like “Create a payment to a landlord.” Well, how do I do that? he wondered. A number of steps are involved in creating a payment, and he didn’t know what they were. The test case was obviously written for someone with a certain level of knowledge about the application. Matt needed more detailed steps.

› Continue reading…

Bookmark It

Hide Sites

As you’re developing a help system and updating content, it sometimes becomes necessary to delete a topic file because the information is out of date or should be combined with other information. When you’re using both RoboHelp and Subversion, it’s easy to mess things up doing this. It’s important to delete the file in RH first to maintain its version of reality and lessen the hassle. But things have to be done correctly in Subversion too.

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

Clarity trumps probably all other considerations in the actual writing part of technical writing. (I say “probably” because anytime you use such absolutes, you can be quickly proved wrong.) In this particular case, it trumps style.

In my role as a reviewer of department communications, I recently edited a document of brief project status reports. One project’s information contained a line like this:

Project objective: Complete the merger of A’s, B’s, C’s, and D’s operations and technology resources.

Now, the use all those possessives didn’t seem right. I checked my trusty Chicago Manual of Style. CMOS 5.27 states:

Joint and separate possessives. If two or more nouns share possession, the last noun takes the possessive ending. . . . If two or more nouns possess something separately, each noun takes its own possessive ending.

Normally, I’d say that each noun’s possessed thing is separate, so each should have the possessive after all. But then again, we’re talking about a merger of those possessed things. So are they actually separately possessed? Or do A, B, C, and D all possess the merged operations and technology resources collectively?

Dilemmas, dilemmas.

So I removed the possessives. But that resulted in a garden path sentence:

Project objective: Complete the merger of A, B, C, and D’s operations and technology resources.

When you first read the sentence this way, it sounds like A, B, and C are being merged, not things that are possessed by A, B, C, and D. Or even that A, B, and C are being merged with D’s operations and technology resources. So I put the possessive endings back in to maintain clarity over style considerations.

My manager—the second-level reviewer—ended up rewriting the sentence completely, but this little episode illustrated to me how asking what version is clearest can settle other questions.

Bookmark It

Hide Sites

As you’re developing a help system and updating content, it sometimes becomes necessary to rename a topic file. When you’re using both RoboHelp and Subversion, it’s easy to mess things up doing this. It’s important to rename the file in RH first so that all links, including in the TOC and index, stay up to date. But things have to be done correctly in Subversion too.

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.

› Continue reading…

Bookmark It

Hide Sites

If you’ve read the responses of the 25 most influential tech comm bloggers and honorable mentions to being listed, you may have noticed that I haven’t said anything about it before now—other than on Twitter the day the list was posted. One reason is that I had other post ideas and some guest posts I wanted to publish first.

Now I’ve gotten around to it.

What Influence Is

Brian Solis recently wrote about how influence has been confused with online popularity. He says:

Over the years, I’ve explored the roles of influencers in social networks and as a result, I’ve refined the definition as simply the ability to cause measurable actions and outcomes. Intentional influence then assumes that certain actions are therefore definable and as a result, desired activity and results are now designed into strategies. The execution of these plans is then dependent on the reach and conviction of the influential voices to which they’re aligned.

One of the classes in my communication minor in college focused on persuasion and social influence. (Yes, majoring in English and technical writing and minoring in communication may be redundant. But the minor gave me a perspective on how people communicate in general, not just how to communicate technical concepts to people.) In this period of the ubiquity of social media, thinking about social influence is highly relevant.

Our textbook was Persuasion, Social Influence, and Compliance Gaining, of which our professor was a coauthor. The book is based partly on the premise that the three named concepts are closely related or synonymous and that they’re aimed at changing people’s thoughts, attitudes, or behaviors.

I believe influence is different than a social circle or even than attraction. Someone may be in my circle without being influenced by me. People may be drawn to my blog through a link on Twitter and never be influenced by what they read. I agree with my college professor’s view of influence: it’s bringing about change in someone else.

› Continue reading…

Bookmark It

Hide Sites

In our ongoing department reorganization, we technical writers are experiencing some angst as we carve out a desirable place for ourselves. However, as we’ve talked about it as a community of practice (no longer as an organized team with our own manager), I think we’re coming to an agreement that now is the time to make things happen—to strike, as Tom likes to say.

After the initial, high-level reorganization, Tom and I are in the same division, so we’ve discussed a plan for taking a more prominent place in project managers’ and interaction designers’ consciousness. This is the key for us because the PMs are the ones to include us in their project plans and budgets, and we would be working with designers to decide on user education approaches and contribute to the design itself.

Finding Tech Comm’s Place in the Family

After Tom’s blog post about our meeting with an interaction design manager, I asked him about his point of view and his readers’ reactions to the post. We discussed getting involved in projects early and contributing to user interface text. We talked more about this in our community meeting this week. Again, we’re looking to make sure that the people who make the decisions give us a rightful place at the table.

We also talked about many designers’ “holy grail” of creating products so intuitive that no documentation is needed. Tom reminded me and then the group of an important point I had forgotten. An interaction designer once said something like this to me, and I had passed it on to the team: “Saying that ‘if the interaction designer does his job right, the product doesn’t need help’ is like saying ‘if the developer does his job right, the product doesn’t need QA.’”

› Continue reading…

Bookmark It

Hide Sites

Guest post by Larry Kunz.

Two years ago I hadn’t heard of content curation, and you probably hadn’t either. Now it’s everywhere. The steam of content is turning into a flood. (Brett Swanson calls it the exaflood.)

As a technical communicator, if you’re not already assimilating content from all across the organization—as well as from your customers—you soon will be. In fact, your customers won’t wait to be invited to the party.

This subject fascinates me, and I like to read everything I can about it. I’m noticing something: as the flood of content increases, the flood of content about content curation is increasing too. Blog posts. Slide decks. Webinars. All with their attendant tweets, RSS feeds, and email notifications.

I’m not alone. As I was preparing this piece, I ran across an article in which Ian Greenleigh wrote that he has trouble handling all of the “shiny” new stuff being written about content curation. Like Greenleigh, I have a column in TweetDeck labeled #curation. Unlike Greenleigh, I don’t have ADD—but I still find it devilishly hard to keep up with everything.

› 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