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

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…

In 2008, Adobe introduced Adobe Community Help, “an integrated online environment for instruction, inspiration, and support. Community Help combines content from Adobe Help, Support, Design Center, Developer Connection, and Forums—along with great online community content—so that users can easily find the best and most up-to-date resources.” Peggy Harvey, a graduate student in tech comm at North Carolina State University, has written and spoken about Adobe Community help as an example of a company engaging users through interactive user assistance.

I’ve used Adobe Community Help when trying to get answers regarding Creative Suite products. I like the emphasis on searching and the integration of results that aren’t within Adobe’s domain. I’m not someone who cares much about rating systems most of the time, with the exception of ratings on open source software. Ratings break down unless you have more than three people leaving ratings.

But I think Adobe Community Help is a great example of what help can be: pulling answers and information together from various sources and formats and then showing context in search results.

So if it’s good enough for Adobe, why are they dishing out AIR Help to technical communicators?

› Continue reading…

In one application I work on, I recently added some text to the context-sensitive help topic for a screen that allows financial secretaries to make a payment. The text described what to do with a particular control that had been added to the screen.

Because of the many variables involved in making a payment in various countries around the world, this screen has become functionally dense, leading to a help topic that I finally decided had become cumbersome. The bulk of it was a procedure for filling out the information, but in between steps was a lot of “if you need to do X, enter Y” and such things. Some of those extra explanations were only a couple of extra sentences, but added together, it was a lot of content being spewed at the user.

This is a Web application, so we don’t have field-level help. The growth of this help topic led me to imagine that if a user clicked Help for information about one particular field and had to slog through the text in that topic, they wouldn’t get very far before giving up. That much information punching you in the face would be enough discouragement without even beginning to scan it.

I needed a different approach.

› Continue reading…

I mentioned in my last post that one of my technical writing colleagues showed the user education team a spreadsheet where he had taken types of information, such as concepts, tasks, and frequently asked questions and indicated what types of deliverables it made sense to use them in.

Historically, I haven’t been a big fan of single sourcing content because I hate it when the content of the manual is exactly the same as the online help. I particularly remember trying to learn the basics of FrameMaker 7.2 in college, only to find that the lack of answers in the online help was duplicated in the manual on the computer lab shelf. So I think experiences like that—where someone thought single sourcing meant the exact same content in different formats—soured me on the idea of single sourcing.

› Continue reading…

Today’s post is borrowing space on Communications from DMN. It’s called “What to Know When Switching from RoboHelp to Flare.” Hope you enjoy.

One of the things I would really like to see tech comm tools do is gracefully handle text boxes across formats. If you ever anticipate having to move content from a HAT to some other format, there’s little incentive to do anything other than a dull, single flow of content. No sidebars using divs because they don’t move well into other file types. I understand that in Flare, divs move well into a PDF, but not into Word.

I would like to see divs in HATs convert into text boxes in Word and into text frames in InDesign (or FrameMaker if that’s your bag). I realize this is mixing vendors and file formats something crazy. But that’s why I’m calling this my “Christmas wish.” I don’t expect it to happen. It would just be really slick if these aspects of various document creation tools moved text boxes nicely when exporting or importing.