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…

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).

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.

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…

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…

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…

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…