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.

Sarah O’Keefe (@sarahokeefe) of Palimpsest tweeted today that according to a webinar she was attending by Ellis Pratt (of Cherryleaf, @ellispratt), nine times more people visit help websites than traditional help systems. This really got me thinking throughout the rest of the day.

If It Looks Like a Help System…

Why would people be nine times more willing to go to a website than an online help system? Since this may have been explained in the webinar but all I have regarding it is Sarah’s tweet, my initial guess is that people tend to think a help system is static and easily outdated (they don’t know about the Agile technical writer?), while a website is fresh and frequently updated. Whether those things are actually true isn’t as important as the fact that the audience perceives them as being true.

This led me to thinking that all is not lost for help authoring tools, though. I’m sure with some effort, I could make an online help system look like a website. Of course, it would take WebHelp to do that convincingly, so this approach may not be possible for all software products.

The first step would be to use some term other than Help. Next, get rid of that traditional side pane, one of the dead giveaways that you’re looking at a help system. RoboHelp and Flare, and maybe others, enable this.

Part of the problem here, though, is that the side pane contains much of the navigation. So it would take putting on the Web designer hat to work out the best way to offer navigation through the help.

› Continue reading…

I’ve got some bad news if you’re a die-hard RoboHelper. No, Adobe isn’t shelving RoboHelp, nor are they reintroducing kadov tags.

I’m being switched to Flare.

Once you’ve come out of cardiac arrest, let me explain.

I’ve said before that I’m not married to any particular tool; I don’t carry around a sign or a mentality that says, “If you don’t use RoboHelp, go jump off a bridge!” The whole HAT wars thing is a bit tiresome. I don’t have any particular feeling toward Adobe, though I’ve heard their customer support leaves something to be desired. And MadCap’s idea of what qualifies as a separate software application bothers me. But they haven’t committed some personal offense against me. (Though back when I evaluated Flare v1 and received a call from MadCap, the person sounded a little offended that I declined to purchase it.)

So since I don’t have some conflict of interest, it comes down to the tools themselves—and what our team is doing. We just hired two new User Education team members, and one is Flare MVP Paul Pehrson, AKA DocGuy. He sits next to me, and in a discussion about Flare that he and another colleague had the other day, let me tell you that the dude knows what he’s talking about. He told me he hasn’t used RoboHelp. The other new guy has used both and prefers Flare. And Tom Johnson is already using it.

› Continue reading…

When we were starting the process of hiring for the two positions we just filled, something one of the applicants said inspired me.

In either his cover letter or resume, he wrote that he had experience using snippets and other features of Flare to execute complex single sourcing. That has made me think about how I can do that in my latest project (using RoboHelp 7).

› Continue reading…