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.