Technically Speaking

My friend Tom Johnson posted an article (new window) last week about the recent release of the Technical Communication Suite from Adobe including RoboHelp 7. I added a comment to his post, but it got kind of long, so I thought I’d post it here with slight modifications. The quotes in this post are quotes from Tom’s post, linked above.

I’ve taken a look at RH7, and I personally wasn’t all that impressed with it. As I’ve watched discussions on RH7 evolve for the last few months, my experience is that people who want to be wowed by RH7 are wowed by it. People who want to be pleasantly neutral are able to be pleasantly neutral. And people who want to hate RH7 find plenty to hate about it. Tom said:

This past month I’ve been heavily using the RoboHelp 7 and Captivate 3 components of the Technical Communication Suite. RoboHelp 7 offers some impressive new features: snippets, breadcrumbs, a pod-based interface that you can drag around, integration with Framemaker and Captivate, and so on.

So basically RH has come out with some of the stuff Flare did, and copied the terminology (”snippets” for example) just to compete. Not particularly innovative, in my opinion, especially when they are a couple of years late to the party.

RoboHelp 7 allows you to begin Captivate movies from within RoboHelp. That way you don’t have to keep re-importing the files each time you update them. […] I ended up deleting the RoboHelp-initiated movies and imported them manually instead (File > Import).

My response is: then how is this good? If you ended up importing them separately, then don’t you have to keep updating them?

Personally, I prefer the way Mimic works for referencing the Mimic project from Flare, then building the Mimic output when Flare is built. You can share variables across products so your Flare variables are available for use in Mimic. That is pretty cool. While Captivate has more features and is easier to use than Mimic, I think you’ll see Mimic improve as MadCap puts more dev time into it, and it is a project that seems be getting some more attention internally. It will be interesting to see how these compare in a year or two.

Later in Tom’s post:

You might also want to be careful about manually editing the css style sheet. […] I recommend using RoboHelp’s official style editor, and perhaps playing with the _ns.css stylesheet that RoboHelp outputs when you generate help.

I hate anything that requires post-processing. A tool that requires post processing for creating WebHelp is broken, in my opinion. I want to be able to build my target and publish it in the next step. (However, I give more allowance for printed output, because there are conventions in printed output that are currently hard to get from the available tools.)

Online Help Quality Plummets

It’s a bitter irony when a HAT vendor produces poor quality help for its products.

Tom then turns attention to importing Frame files into RH7:

Framemaker Import Groundbreaking But Irrelevant for Me
[…]
Flare is developed by a team that is experienced with help authoring, and—perhaps the most confusing distinction—Flare seems to support FrameMaker more thoroughly both for importing and exporting content than does RoboHelp.

It’s ironic isn’t it? MadCap’s product does better with Adobe’s own FrameMaker than Adobe is. But I don’t get how this is groundbreaking? I mean, Flare does this and does it better. In Flare you can round-trip your FM files. THAT is groundbreaking and innovative.

I believe this is indicative of a larger problem within Adobe: they purchase a product then get rid of the developers who understand the product. Adobe is having trouble updating and making Frame compatible with other Adobe products because it seems they don’t understand the code behind what it does. I also wonder if they really understand the RoboHelp code enough to update it to compete in the new space (now that it has to compete with Flare, AuthorIT, and others).

It will be very telling to see what happens in the next RoboHelp release. Frame 8 is bascially Frame 7.2 with a new UI and a couple of upgraded features. But there isn’t any competition out there pushing Adobe to make a better Frame. RoboHelp is now in catch-up mode trying to figure out how to emulate the innovative features in MadCap’s product suite. Now it is MadCap pushing the innovation envelope here. Will RH be able to maintain pace with MadCap’s one (or more) releases per year? Will RH be able to come out with new features that aren’t already in Flare? Maybe so, but RH 7 wasn’t proof of that yet. Again, it will be interesting to have this discussion in two years and see where the major players are at.

In Tom’s conclusion he states:

RoboHelp continues to ignore some major issues, such as the lack of character-level indexing and the formatting errors when you export to Word. Despite my complaints, I like many others have an affinity for the usability of this tool. It’s like an old pair of sneakers that has some new laces and polish. Maybe some new traction too.

With his conclusion, he supports my theory that those who wanted to like it do like it. Despite all the problems Tom enumerated in his post, he still have a favorable impression of RH–a tool he has used in the past with good results. I tested RH7, and I’m very glad my primary HAT is Flare.

But to each their own. If anything, I hope a healthy competition between Flare and RH continues because that will help both products improve. Frame is a great example of how a product can go stagnant when no outside competition drives the need for new changes and features.

The Utah State Capitol building has been closed for more than three years for a renovation project. The building has received a seismic upgrade in addition to being restored to the original architect’s vision and specifications. On the anniversary of Utah’s statehood, January 4, 2008, the Capitol will be re-opening and will be re-dedicated.

The Lt. Govenor’s office in conjunction with the Capitol Preservation Board is holding a week-long open house and celebration. To accommodate the thousands of expected guests, the state of Utah is seeking volunteers to assist in the event. Volunteers are needed for four-hour shifts during the week of Jan 4 through 12. If you can donate four hours of your time to the people of Utah during that week, I invite you to join me in volunteering.

More information is available at the volunteer registration website.

I hope to see you there.

I stumbled across a cool feature in MadCap Flare v3.1 the other day. I doubt this is a new feature; rather, it is one I just didn’t know about.

There are several ways to create links in Flare, some easier than others. Normally, you would just chose an insertion point in your topic, then from the Insert menu, click Insert Hyperlink (or you could use the Ctrl+K key combination).

Today I want to talk about the following link creation shortcuts:

• Dragging links
• Context menu linking

Dragging links

If you want to insert a link from one Flare topic into another topic, the quickest way to add the link is to drag the target topic from the Content Explorer into the Topic in the XML editor.

Say you are editing TopicA.htm and you want to link to TopicB.htm. Open TopicA.htm in the XML editor. Find TopicB.htm in the Content Explorer. Drag TopicB.htm from the Content Explorer into the XML editor, dropping it where you want the link to appear. A dialog box will allow you to modify the settings for the link. Click OK and the link is inserted into your topic.

This is especially useful if you are linking to a topic in a different folder in the Content Explorer, since using the Insert Hyperlink dialog box to locate a file in a different directory is kind of a pain.

If you want to add a hyperlink to text that already exists in your topic, you can highlight the text, and then find the target file in the Content Explorer, and drag it to the highlighted text. The highlighted text will turn red before you drop the link on it, so you know it has been selected. You will see the Insert Hyperlink dialog box. Click OK and the highlighted text is changed to a link.

I only wish there were an easy way to make these into cross-references, instead of hyperlinks. What I’d like to see here is a Ctrl+drag combination or a right-click+drag combination that would insert a cross-reference to the topic, rather than a hyperlink. I guess I’ll submit a feature request.

Context menu linking

There are several options in the context menu for inserting hyperlinks and cross-references. (Unfortunately these don’t work properly when you are modifying text the MadCap:Drop-down-body element.)

When you are working in a topic in the XML editor, you can use the Context Menu to quickly create links and cross-references; the process is the same for both.

The Quick Link and Quick Cross-Reference options allow you to easily link to topics in the same folder, topics that are open, or bookmarks in the current document.

To use the Quick Link / Quick Cross-Reference functions, open your topic in the XML editor. Right click at the location where you want to insert the link (or cross-reference). The context menu appears (shown above).

For Quick Links, you can insert a link to a bookmark, a topic in the same folder, a new topic (that you will create by selecting this option), or to any topic in the project (a window will appear so you can browse to the topic).

For Quick Cross-References, you can insert a cross-reference to a bookmark, a topic in the same folder, or an open document.

Often, when I’m creating a cross-reference to a topic in a different folder, I’ll open the topic I want to cross-reference to, then open the source topic and insert a quick cross reference. The only problem with this method is that you don’t see the Insert Cross-Reference window, so you can’t pick the cross reference properties. I have three different cross reference styles, and the Quick Cross-Reference feature uses the default one. (I actually don’t understand why this doesn’t work in parallel with links; when you insert a Quick Link, you get the Link Properties window, but when you insert a Quick Cross-Reference, you don’t get the Cross-Reference Properties window. )

There is your Flare tip on easy methods for inserting links and cross references—allowing you to author your help content more efficiently.

(This is part five of a five-part series dealing with content reuse in the Help Authoring Tool (HAT) MadCap Flare version 3.1.)

Review

It’s time for a brief review: When we talk about content reuse, we mean writing content once and then creating multiple outputs from that single source of content. Flare is a help authoring tool created by MadCap Software that allows you to single source your content in powerful ways. Flare includes tools for using variables, snippets, and conditional text to create a powerful source from which you can create multiple output targets.

Variables are small strings of text that you can replace for an entire project, and can even change for individual targets. You might include your product name and version as a variable. When this information changes, you can change the variable definition, and the project is instantly up-to-date. Snippets are like large variables. They are actually entire XML files that can include images, text, formatting, etc. You can use snippets for chunks of information that you re-use in multiple topics in your project. When you need to change that information, you change the snippet file, and all the topics that include that snippet are instantly updated. Conditions allow you to mark content (all the way from the character level up to the entire topic level) with conditions. When the project is built, you can include or exclude content marked with those conditions. For example, you can have one topic that includes some information or terms used in printed output, and other terms or information for use in online output.

Project Application

Today I thought I’d talk about a fictional project and show how with proper use of content reuse tools you can create several distinct outputs from a single source of text.

Suppose you are writing a user guide for a product we’ll call Widget. You give a basic version of Widget away for free, but you have a version of Widget called Widget Plus that requires a subscription. You have an OEM agreement with another company, and they bundle Widget Plus with their application, but they call it Super Widget. (For this example, we’ll assume the content in Super Widget is exactly the same as the content in Widget Plus; the branding, colors, and product name are the only differences. We’ll refer to these two versions as the advanced version of the application.)  All three versions have online (F1) help. Widget Plus and Super Widget also have printed guides (provided in PDF format).

In an old-school style help system without tools for content reuse, you would probably have to create several different projects; You’d need:

• Online help system for Widget
• Online help system for Widget Plus (with added functionality and Widget Plus name)
• Online help system for Super Widget (with corporate branding of affiliated company)
• Text-based project for Widget Plus
• Text-based project for Super Widget (with corporate branding of affiliated company)

You recognize that these five outputs contain sections that are very similar (or even the exact same content in some cases, with just the name changed) but you end up maintaining five separate projects because you need five separate outputs.

Single sourcing with Flare (or another similar HAT) means you only need one project. You add all the content to the one project, and you just create five different output targets. Then you use the content reuse tools in your HAT to simplify the process.

In this project you would create two different TOCs and five different targets. You would want a TOC for the simplified Widget application, and a TOC for the advanced Widget Plus and Super Widget applications. You would create a separate target definition for each of the outputs I listed in the bulleted list above.

For this project you’d want to use a variable for the project name. Every time you reference the project’s name, you’d use the variable instead of Widget, Widget Plus, or Super Widget. In your topic you might see something like:

The Preferences screen allows you to customize the [variable:ProjectName] interface.Then, in each of the five target definitions, you’d update the variable definition. When each target is built, the proper project name is automatically inserted.

If you have chunks of content that you reuse in multiple topics, you can create snippets to allow you to reuse those content chunks across multiple topic files.

Then you would use conditions to customize your outputs.

For this project you might have the following conditions:

• Basic
• Advanced
• PrintOnly
• OnlineOnly

One way these conditions can be applied is to content within topics. The Preferences screen for the basic application may have fewer features than the Preferences screen for the advanced version of the application. You still only need one Preferences topic in your application. This topic includes all the features. The extra features can be marked at the paragraph level with the “Advanced” condition. The targets for Widget can be set to EXCLUDE the Advanced condition, and this advanced content is not included in the basic version’s help system.

You can also have text on the screen marked for online output only, with other content marked for printed output only. You might have the following text:

This [condition:print]guide[/condition][condition:online]help system[/condition] documents [variable:ProjectName].

The online help systems can include the “OnlineOnly” condition and exclude the “PrintOnly” condition. The printed guides can include the “printed” condition and exclude the “online condition.

In our fictional project this one sentence can be rendered five different ways, depending on the settings in the target file:

1. This help system documents Widget. (“OnlineOnly” condition, “Widget” variable definition.)
2. This help system documents Widget Plus. (“OnlineOnly” condition, “Widget Plus” variable definition.)
3. This help system documents Super Widget. (“OnlineOnly” condition, “Super Widget” variable definition.)
4. This guide documents Widget Plus. (“PrintOnly” condition, “Widget Plus” variable definition.)
5. This guide documents Super Widget. (“PrintOnly” condition, “Super Widget” variable definition.)

You can also apply these conditions at the file level. You might have a feature that is only available in the advanced versions. You can apply a condition to this topic in the Content Explorer, and that topic will only be included in the advanced outputs. (Your basic TOC wouldn’t include the advanced functions obviously, but for a WebHelp target, the actual files will still be copied over, and would be available in a search. If you exclude the topic however, the files simply won’t be included at all in the output.)

To get the branding right for the OEM-ed Super Widget, you might create an additional style.css file, separate masterpages for printed output and online output, and a separate skin for the WebHelp output. In the target definition files for the Super Widget targets, you would change the style settings, masterpage settings, and skin settings to use these Super Widget-specific files.

Conclusion

I hope you can see the power in single sourcing your content. The content reuse tools in MadCap Flare are powerful. You can use a single project for an unlimited number of outputs. Your imagination is your limitation.

This concludes my five-day series on content reuse in MadCap Flare. Feel free to share your comments with me, either as part of the posts in this series, or by contacting me via my contact form. You can also look for me in the MadCap user forums where I go by the name Doc-Guy.

Good luck single sourcing your content. It is worth the effort.