Question About DITA Topics Created Using Flare 5

At my DITAbug presentation on Wednesday night, I was asked whether DITA topics created in Flare by exporting Flare's native XHTML to DITA were well-formed or valid. This proved to be a fairly unusual question and it took several phone calls to track down the answer.

The answer, with one caveat, is that the DITA files should be valid per the OASIS DITA DTD. If they are not, there's a bug and the problem should be reported to MadCap. The caveat is that Flare 5 does not support specializations.

An Addition to the Previous Post...

I Forgot...

A tip of the hat to Alvaro in MadCap tech support for clearing up a point about the style properties groups. Thanks...

Notes about Flare’s Style Sheet Editor

Flare’s style sheet editor is very powerful but has several attributes that can be confusing.

One such attribute is the variety of styles, including unusual ones like "generic pseudo-class". Another such attribute is the many properties available for those styles. Another is the combining of the properties into functional groups like Font, Background, or Block, which means that a property can appear in several groups.

This last attribute raises two questions – what do the different functional property groups do? And, if a property appears in several groups, is it the same property each time?

I’ve heard these questions often but never got around to writing anything about them until getting a question (thanks, Jennifer) in a CSS course that I recently taught for MadCap. The question was – “I don't understand the difference between padding in the Box, Cell, and Padding groups in Flare’s stylesheet editor.”

As noted above, MadCap combined many style properties into groups depending on their function. This means that some properties, like Padding, will show up in multiple groups because padding applies to different functions, like paragraph and table cell formatting.

Are the repeated properties simply the same property used in several places? To check, you can list all the properties using the Show: Alphabetical List option on the style sheet editor’s toolbar. If a repeated property is actually the same property, it will show up once in the alphabetical list, exactly what happens with the Padding properties.

Regarding the three functional groups in the question above – Box, Cell, and Padding:

- If you want to format a table cell, use the Cell or Box group properties.

- If you want to format a text paragraph, use the Box or Padding group properties.

Each case, table cell or text paragraph, can be handled by the properties in either of two functional groups, so you'd choose between those groups by finding the one that offered the specific properties you needed. For example, if you want to format a table cell and need to set the margin, select from the Box group. If you didn’t need to set the margin, you could select from either group.

Some Thoughts about “User-Generated Content”

These days, the term “user-generated content” is usually interpreted as content generated by users via mechanisms like blogs, wikis, Twitter, etc. But there’s another way to view the term that I’ve run into recently – content generated by SMEs (subject matter experts) via Word (can also be Frame), to be automatically turned into online help using a tool like Flare or RoboHelp. In other words, an online help project in which the SMEs do the work, with little need for an online help developer after the initial project setup. I’ve run into two such cases in the last three months, both involving Flare.

Both clients wanted to take material written in Word by SMEs and convert it to WebHelp help format. The material changed often – daily in one case – and passing it through a Flare developer was a potential bottleneck. So the idea was to buy Flare and set up the project using the auto-reimport feature. When it was time to generate the output, this feature would check the imported Word file to see if there was a later version and, if so, reimport the new version and regenerate the WebHelp. Could this work?

The answer is yes, with one big caveat. Reimporting the Word file overwrites the results of the previous import. This isn’t a bug; it’s just the nature of a reimport. But the result is that, until the vendors change how their reimport feature works, it means that SMEs can only use features that they can add in Word. Flare-specific features won’t work, and Flare simply becomes an output generator. Why?

Let’s say you import a Word file into Flare and, by breaking the file at the level 1 heads, wind up with ten topics. You then add Flare-specific features, such as links or index entries, to those ten topics, and clean up any bad formatting that crept into the Word file. As it often does…

The problem is that the next time you reimport that Word file into Flare and wind up with new versions of those ten topics, the new topics overwrite those from the prior import and all your Flare-specific features and formatting corrections will be gone. You’ll have to recreate them. This usually isn’t hard, but it’s time-consuming and reduces the automated component of the publishing that the client wanted in the first place. According to MadCap tech support, there’s no workaround to this problem. The nature of a reimport is that it over-writes the topics created in the prior import, period.

So this issue has at least two ramifications if you’re looking for a way to automate the process of creating online help.

First, because the reimport overwrites the topics in Flare and any Flare-specific features added to those topics, all the writing, formatting, linking, indexing, etc. must be done in Word since that’s the only way to guarantee that those features won’t be overwritten. In effect, Flare becomes an output generator rather than an authoring tool.

Second, the overwrite of the topics also means that formatting corrections that you made to the Word file prior to importing it into Flare will be lost; you’ll have to make those corrections again on the next reimport pass. For example, if an SME used local formatting on a table and you had to fix that formatting to get the table to display correctly online, you’ll have to fix that formatting again on the next reimport pass. The only solution to this problem, and it’s far from foolproof, is to get the SMEs to use Word correctly, or at least less incorrectly. Provide them with Word templates, sell them on the idea of using the templates, and teach them how to use the templates correctly.