RoboHelp 8 and DITA

If you use RoboHelp 8, you can start getting your feet wet with DITA without necessarily buying a DITA authoring tool. You can’t create DITA maps or topics – that capability won’t be available until, presumably, RoboHelp 9. But you can import DITA maps and topics into RoboHelp 8 to see how well it handles DITA features and how well it turns the DITA material into outputs like WebHelp.

The sticking point is that RoboHelp 8 uses the DITA Open Toolkit (OT) to import DITA material. This means you need the properly configured OT on your PC. If you typically work in RoboHelp’s GUI, installing and configuring the OT will be far more techie than you’re used to. The instructions below should help make the process easier. (Note that some version numbers may have changed since I wrote this. In particular, v. 1.4.3 may have been replaced by v. 1.5.)

Download and unzip the OT from:

http://sourceforge.net/projects/dita-ot/files/#

This will create, among other things, a folder called doc that contains the installation instructions.

Then, if you’re a Windows user, follow the instructions at:

C:\ditaot\DITA-OT 1.4.3\doc\ installguide\windows_installing.html

A crucial step is to be sure your environment variables are correct. You’ll know if they aren’t if you try to import a DITA map into RoboHelp and get this message (shortened somewhat here) in RoboHelp’s Output View pane:

C:\DITA-OT1.5\build_preprocess.xml:269: java.lang.VerifyError: (class: topicpull, method: …
...
Inconsistent stack height 1 != 0

Again, this probably means your environment variables aren’t set correctly. To fix them, follow the instructions in the document at:

C:\ditaot\DITA-OT 1.4.3\doc\installguide\ windows_settingenvvariables.html

However, be aware that some of the settings needed for your PC, particularly the JAVA_HOME setting for the folder where you installed the JDK, may differ from those in the setup instructions.

Note also that some environment variables are optional. For example, if you do not plan to output JavaHelp, you can ignore the JHHOME setting. If you do not plan to use the Apache FOP, you can ignore that setting for the CLASSPATH variable. Ditto for the Xalan setting for the CLASSPATH variable.

Note also that some of these settings are long and complex enough that you do not want to type them if you can avoid it. An easier thing to do is to open the environment variable instructions file (… windows_settingenvvariables.html), copy the value of each variable field that you’re modifying and paste it into Notepad, copy the value to be added for that field from the instructions in the …windows_settingenvvariables.html file, and paste it into the code in Notepad, and finally copy the code out of Notepad and paste it into the appropriate variable field. As messy as this sounds at first, it’s actually straightforward with less risk of typographic errors.

Finally, note that I'm not getting into the specifics of variable settings, especially for the JDK, since it will vary depending on which version you have. But email me if you have specific questions and I'll try to answer them.

You’ll know that you’ve set all the environment variables correctly if you try to import a DITA map and get the “import successful” message in RoboHelp’s Output View pane.

How long will this take? If you’re accustomed to commonly working at this level of technical detail, about an hour. If you’re not, plan on two to three hours. This may be a big chunk of time in a crowded schedule, but it’s a small investment in time that can open up a whole new feature set in RoboHelp.

If you’re interested in more information about how help authoring tools (HATs) are starting to support DITA, I’m giving two presentations at Lavacon in New Orleans in late October, one on how to use HATs to work with DITA and one on how to use HATs to create simulated CMSs. If you’re not going to Lavacon, I’d be happy to send you copies of the PowerPoint slides after October 30.

A Potential Problem Importing RoboHelp HTML 8 Projects Into Flare 5

Flare’s Import Project feature (File > Import Project) can pretty easily import RoboHelp HTML projects except, in some cases, projects from RoboHelp HTML 8 (hereafter RH 8). One such case may be if you moved an old RH for Word project into RH 8 and then decide to move it to Flare. You may find that some topic files in the project contain RH-specific XML processing instructions that look like this:

If you try to import a project whose files contain these codes into Flare using the Import Project feature, Flare will display an error message for each file that contains such codes and not import those files.

To import those files using the Import Project feature, you first have to open each file in Notepad and delete the entire processing instruction code. You can then import the project, and those files, into Flare using the Import Project feature.

Deleting these processing instructions is easy but tedious because the code may appear in several places in each file, with different syntax, so you have to find and delete each one individually. The differing syntax and multiple lines of code make it hard to reliably use large-scale search-and-replace.

The best solution is probably to wait until MadCap modifies Flare’s Import Project parser to handle RH HTML 8 in a later release. But if you can’t wait, there is a workaround…

Start a new project in Flare and just import the topic files into the project like any HTML or XHTML file. The files will come in, but will show the processing instruction codes when you view the topics in Flare’s XML Editor. Fortunately, users won’t see them in the output. They’re just visually intrusive to us, the authors, while we edit the topics, so we can either delete the codes or just ignore them.

Remaining Questions From the Captivate 4 STC Webinar

From Peter I – How… set Captivate closed captioning to "ON" by default? – The easiest way I found to do this is from http://www.raisingaimee.co.uk/index.php?option=com_content&task=view&id=35&Itemid=28. Thanks to Captiv8r for pointing this out on Adobe's Captivate forum at http://forums.adobe.com/message/153596#153596

From Judith S - Does Captivate 4 capture right-mouse clicks? – Yes, but it has a few quirks and can vary depending on the version of ActionScript. See this thread on the forum - http://forums.adobe.com/message/2058434#2058434.

From Debora G - …published captivate files are of poor quality (fuzzy text and background image) - how can we improve the quality? When we preview in CP it looks crisp – Did you insert the image as a bitmap (GIF, JPG, or PNG) and have you scaled the movie? Let me know by email offline.

From Linda K - is there a way to correct typos made during capture so they're not repeated in the output? – Per Peter I – “One can replace the original typing with animated typing text.” Is that what you need?

From Linda K - when should we use auto recording mode vs full motion recording? – Basically, use auto mode to record standard movies and fmr to record movies that show continuous visual change like drag and drop or, on the more unusual side, something like the view through an electron microscope. Note that you can start recording in auto mode and switch in and out of fmr as necessary by pressing F9 to enter fmr mode and F10 to return to normal.

From Linda K – how… control the size of the frame in the SWF output? – This question may be referring to two things, so I may not be answering the right one. Read this thread on the forum - http://forums.adobe.com/message/718082#718082 – and let me know if that’s NOT what you were referring to, in which case we can talk a bit more offline.

From Linda K - how do we remove the Captivate branding from the... player? – If you’re referring to the Adobe Captivate “button” from the playbar, open the skin editor (Project > Skin Editor), select the Playback Control tab, open the Playbar field pulldown, and select any playbar style other than default.

From Judith S - Can you demo or show us the aggregator? – Are you asking in terms of how it works compared to MenuBuilder or just in general? Shoot me an email offline if you have a chance.

From Judith S - How easy is it to translate… Captivate movies from English to another language? – I’ve done little translation work so this response may not be complete, and I ask anyone who has translated to extend or correct what I say next... It seems fairly straightforward - pick the desired language for the auto-captions and modify the text as necessary, translate your text captions, and re-do any voiceovers (obviously). You may also have to re-shoot any screens in the appropriate foreign language version of your software. Also watch for culturally-based issues. One example that I ran into years ago was the use of a rural post box icon as an email icon, only to find that many people outside the US didn’t know what it was.

From Jeff F - …explain more about widgets? – There’s a pretty good write-up on them in Captivate 4’s help, but email me if you’re looking for more than what’s there and we can discuss it.

Enjoy the tool...

Attendee Questions From My Captivate 4 STC Webinar Last Week

Thank you all for your questions. Here's the first set of responses. Look for the rest over the next few days...

From Cynthia K - file sizes for the two examples you showed - The SWF for the Decimal-Binary Conversion movie was 249K. The SWF for the diaper-changing movie was 2.45 Megs.

From Michael M – …interactivity capabilities of Camtasia vs Captivate? – Overall, I’d say they’re similar. They're both major commercial tools, which usually means they support the same overall set of features and differ in specific areas or capabilities – e.g. they both offer text caption boxes, for example. Check Camtasia’s features at www.techsmith.com/camtasia/enhance.asp for specifics.

From Don W - What is the output format for... Captivate? – There are seven options. I’d say the most common is SWF for the movie, then Print (Word) for producing review copies or handouts. You can also output to Adobe Connect Pro, AVI, EXE, an email attachment with several specific formats, FTP, or a new (in Captivate 4) AIR-based “review” format as a way to move reviews off paper.

From Erin H - can you talk a little bit about how it integrates with other help systems? What things should we be aware of? I woudl like to include movies in online Help (and we use a content management tool for Help). Also, what can be done to minimize file size? – In Flare and RoboHelp, and probably any other tool that lets you insert SWF files, it’s a simple matter to insert a movie into a topic. The problem is that the movie runs automatically every time the user opens that topic, cool at first but wearing thin fast. A better solution is to create a separate topic to hold the movie, then add some link text in the main topic, like “Click here to see a demo” and popup link that text to the help topic that contains the movie. This lets the user decide whether to run the movie. Two points re minimizing the movie files sizes… First, reduce the number of graphics that you insert in the movie. Second, if you’re doing audio narration, do it in one or two takes rather than twenty or thirty to get the audio "just right", since all those takes add up.

From Cynthia K - how many tiers can you branch out to? – As far as I know, there is no technical limit. The only limit may be how many you can keep track of.

From Peter I - can you suggest approach for maintaining captivate movies? For ex., if one screen changes. – I think it depends on the size and nature of the change and its proportion to the overall movie. Overall, there are two main options. Re-shoot the changed material as a new movie, then import its frames into the existing movie and delete the original, now-changed, frames. Or, delete the old slides in the movie and use Cap’s re-record feature ( Insert > Recording Slide). I lean toward the first option because I find it less confusing, but that’s me.

From Susan H - Can we change text to variables after the fact? – You can remove text and replace it with a variable, if that’s what you mean…

From Linda K - may we use the music shipped with Captivate in our movies? are they copyright concerns? – As far as I know, the audio clips that ship with Captivate are freely distributable with no copyright issues, but don’t take my word for this. I'd contact Adobe to check, or else have your legal department do so.

From Susan H - Please confirm that Captivate DOES support double-byte characters. – Per the features page at www.adobe.com/products/captivate/features/, under the Unicode Support heading, it says “Create your content in any language, including double-byte languages, and count on Adobe Captivate to publish it properly thanks to Unicode text encoding”

From Linda K - How to change the default text used in the automatic captions? – Open the appropriate CaptureTextTemplates_.rdl language file in the Program Files\Adobe\Adobe Captivate 4 folder and change the default text as needed. This file is a bit programmatic, so make sure you’re changing the right wording. Back up the original RDL file before changing it.

From Erin H - perhaps you could post a short demo of using Captivate on your blog? – I’m going to run a brief (35 minutes) demo on Wednesday. Let me know if you’re interested in sitting in and I’ll send you the connection info.

More to come...

About That Issue of Tech Writers and Business

I've heard from two people, so far, who read something other than what I intended into what I wrote about tech writers and business, so...

I don't assume that tech writers are incompetent or incapable of understanding business issues. Nor do I hold tech writers who come from fine arts or English backgrounds in disdain. (I have a bachelors in English myself.)

I simply believe that too many tech writers just don't want to get involved in the finance side of business, an attitude that holds those writers back from having a more influential role in their companies' operations. If tech writers are going to compete with consultants and outsourcing and offshoring firms, we need to be able to hold our own in business terms during operational discussions. That's it...

Why Tech Writers Need To Understand Business - Yet Another Example...

For some years, people, myself included, have noted the lack of interest, even disdain, that many tech writers have for business issues. This reduces these writers' ability to affect company decisions, including decisions that may affect them.

One area in which this problem manifests itself is finance. Writers from fine arts or English backgrounds can rarely discuss cost-justification in finance terms, so they have little input on buying decisions. Consider the decision to buy a $100K+ CMS. Spending that much money may require formal cost-justification. If the doc group can't provide it, then either the CMS won't get bought or will get bought but under the control of another department that may or may not take the doc group's needs into consideration.

But there are other areas in which ignorance of business can hurt. One, security, was the subject of an article in a recent issue of Business Week (July 27, 2009, "Google's Battle for the Office"). Here's a quick backgrounder...

Google appears to be attacking Microsoft by undercutting Windows and Office. Google's Chrome browser will let users run applications, like word processors, that reside on a server rather than on users' desktops. And Google's application suite, Google Apps, is intended to compete with Office but with the applications also on a server rather than users' desktops. Undercutting Windows and Office would reduce Microsoft's revenue stream and thus weaken Microsoft.

Love or hate Microsoft, there is some benefit to Google's approach and Google is pushing it. The problem, as the Business Week article noted, is security. Google Apps stores files, like word processing documents and spreadsheets, on Google servers rather than on the client companies' own servers. This means the client companies give up control of their proprietary material. Quote Business Week - " For some companies, the arrangement violates security and accounting policies."

Business trumps technology...

Questions from the July 7-10 Remote Flare 5.2 Course

Re looking for the definition of "inline marker" as an impromptu test of the help's usability... I found it in under a minute by opening the help Search pane, searching for "inline", clicking "inline markers" in the auto-complete panel, opening the first topic - "Frame Contents Window Pane," and scrolling down until I found the two words highlighted. Here's the definition, from the v. 5.2 help...

"...markers for all inline elements in the active topic. You might find this feature useful if you have imported DITA file content. The reason for this is that DITA inline tags are often for semantic purposes, rather than for changing the look of content. By enabling the inline markers feature, it is easy to tell when particular content is using a tag."

The problem here is the need to scroll almost halfway down the topic to find the definition. However, the highlighting helps. So I'd call this pretty usable...