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

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

One day I spent much of my time with a person who was new to a desktop application I work on. I provided documentation for the application, but this particular person—I’ll call her Ann—tends to doubt her ability to learn. So I was happy to work with Ann one-on-one to help her learn the steps of a procedure she would use at least weekly (and that she knows well at this point, I’m happy to report).

As we talked, Ann decided to open a new Word document to work in. I watched as she went into her file system and located a document with the file name “blank page.docx.” She double-clicked it to begin a new document.

I was somewhat surprised and even a little amused.

› Continue reading…

Bookmark It

Hide Sites

I started my current job five years ago this week. Reaching the level of senior technical writer brings me to ask whether I’ve got the smarts to go along with the time I’ve clocked.

A Narrow View of Tech Comm

When I graduated from Utah State University two months before starting as an intern, I thought technical communication consisted mainly of writing manuals, help systems, and the occasional tutorial. I thought the main activities were writing and creating images for print or Web.

My definition of a technical writer didn’t differ much from most people’s if at all.

I hadn’t heard the terms CSS, single sourcing, structured authoring, DITA, social media, Agile, RSS, SEO, or content strategy. Some of these things were either relatively new or not dreamed of at that point.

I belonged to the student chapter of the Society for Technical Communication, but the chapter members mainly learned from each other. There was only so far we could go that way.

› Continue reading…

Bookmark It

Hide Sites