Workload for Flare Migration Project

[adhollyhock]

Our team of three technical writers is considering migrating from Word to Flare in the next weeks. We will have to import around 40 user manuals (3000 to 4000 pages). We currently only produce PDF, and we will produce PDF and webhelp output after migrating to Flare.

My current concern is to estimate the workload for the migration project. I have made an initial planning on the various implementation steps: configuration, preparation of Word documents, import, organization of the content in Flare, and creation of the content in Lingo for 4 languages (based on existing translation memories).

I would like to hear about your experience and the workload of each implementation step in your migration project.

To speak about the same things, I specify below the tasks we would perform in each implementation step:
- The configuration step will include the following tasks: defining CSS, page layout, master pages, strategy on how to use conditional tags and snippets, variables, statuses, template/generic topics, various proxies for the PDF and webhelp output, strategy for table management, image management and version management (using Subversion or another Version Management System integrated with Flare).

- The preparation of documents in Word obviously depends on the initial Word documents. We have a quite simple template, we use a set of 20 Word styles and the information is well structured.

- The import and organization of content in Flare could include the following tasks: importing the content, organizing the topics in folders, adding conditional tags and snippets, adding cross-references, “single-sourcing” about 1350 pages, adding variables, applying proxies like mini-tocs, tocs for output, etc. This does not include ‘redesigning’ the content to adapt it to the online help output.

Thanks in advance for your input.
Best regards

[lacastle]

Do you have specific questions about this?

In general, it's a lot of work to migrate if you are learning Flare at the same time. Familiarize yourself with Flare first, creating templates and styles and targets, and the whole process will be easier.

[i-tietz]

Honestly: I you're planning to do it in the next weeks, this question comes far too late.

We swapped in Flare for RoboHelp more than 3 years ago, and it took me about two full months to work out a detailed catalogue of what to do in what order. A lot of testing was needed. I imported our most complex and biggest project to Flare for about 50 or so times to work on the precise steps of the proccess. I put it down in a transformation guide, made checklists for all procedures.

We also had to stuff it into Source Control (MS VSS), we have "central" files we use in more than one project and we applied conditions. The "after"work was something like this: add links to conditioned topics (topic A has condition X, topic B has condition Y, in topic Z you have to insert a second link to both files - and you have to assign conditions to those links), check the imported content, eliminate the RH javascripts that have no function in Flare, check whether all styles are producing the correct output (tables and popups caused me a lot of "fun" there), check and correct the index or the CSH links, etc.
Believe me: There are pitfalls almost behind every corner.
You gotta have thorough import and working tests - you will have to test the full length of everyday and extraordinary work before anybody is going to do that seriously. Otherwise you might regret it ...

[schultza]

We are in the same boat. A team of 4 writers with A LOT of stuff to migrate from Author-it into Flare.

All our templates, style sheets, etc. are finished, and we have practiced many times importing a few documents; we've imported both Word and .chm versions. Either way, we still end up doing a lot of formatting post import, which is time we cannot afford when we are trying to maintain the documentation at the same time.

Do you have any suggestions for us based on your experience? How did your migration turn out?

[i-tietz]

We are in the same boat. A team of 4 writers with A LOT of stuff to migrate from Author-it into Flare.

All our templates, style sheets, etc. are finished, and we have practiced many times importing a few documents; we've imported both Word and .chm versions. Either way, we still end up doing a lot of formatting post import, which is time we cannot afford when we are trying to maintain the documentation at the same time.

Do you have any suggestions for us based on your experience? How did your migration turn out?

You imported .chm? How's that? Did you decompile and import the HTML Help project? That should give you quite a good result. If the looks are ok that might five you time to do the "cleaning" afterwards - you can do it step-by-step instead of all-at-once.

If you can make out certain patterns in what format/style you change into what other format/style you might be able to use a text editor that can do:
- batch find&replace (to change a whole project in one go)
- using regular expressions (to limit the number of find&replace runs)

It might be worthwhile to find a tool and learn about regular expressions.
I used "Textcrawler", which
- gave me the opportunity to try searchstrings and regular expressions BEFORE really changing files
- had the nice feature of saving find&replace strings including regular expressions, so everybody else using the tool could perform the same find&replace on another project.

[schultza]

We are working in Flare V7.1, which has a feature to import the HTML files that make up the .chm. Navigate to Project > Import HTML Files to open the wizard and locate the files.

Thank you for your suggestion! I can see how this will initially require some planning and procedure development (especially since half my team does not know HTML), but I can already see from looking at the source code of pre-conversion and post-conversion side by side (prior to importing you can preview the conversion) where I could do a find and replace in my original HTML files to find class="note-vs" and replace that with class="note".

Thanks! (Though I welcome any other suggestions as well.)

[doneal]

Looking at your dates, this is probably too late. But, just in case...

In a migration plan, we need to include "Author Training". Also, while thinking this way, we should include "Definition of Roles". What are the differences between "Author" and "Administrator" in particular.

I have been holding off converting Robo to Flare simply because it took a couple years to get authors confortable with Robo (they are subject matter experts and don't particularily want involvement in the finer points of technical writing/systems) and the Robo XML editor seems non-intuitive to me. Anyway, I'm not sure I want to spend another couple years trying to get folks up to speed and also fixing the many problem that slip into the files when there are multiple authors.

Thus, we should plan initial user training and what amounts to an in-house help desk for the first year or so of operations.

Thanks, Dennis ONeal

[schultza]

I can't speak for adhollyhock, but my company is on the slow road to getting migrated, if even at all. Our department keeps shrinking; the original manager/purchaser of Flare and our editor (its endorser and administrator) left our company within 6 months of our Flare purchase. Because of the manpower shortage and the difficulties we have encountered coming up with a process that saves us enough time migrating documents, our new manager is now evaluating whether Flare is the right tool for us before devote any more time.

[i-tietz]

Because of the manpower shortage and the difficulties we have encountered coming up with a process that saves us enough time migrating documents, ...

Ever thought of having somebody external developing the migrating process or even doing it for you? I know - that costs ... but that's the price the company has to pay for getting rid of people who could do have done the job. If the job has to be done it has to be done.
In Germany we have a saying: "You gotta die one way or another."

our new manager is now evaluating whether Flare is the right tool for us before devote any more time.

Always the same with new staff trying to leave their marks, eh? ...

p.s.: "Manpower shortage" ... that's a neat and inventive term ... "people got kicked out" - how boring to say it straightforward ...

[crdmerge]

A few issues in the RH-to-Flare conversion, both of which cause all subsequent content to be stripped from the topic:

* RH spell check "ignore" tags (<?rh-ignored text="MyIgnoredText" ?>) when encountered twice in the same paragraph.

* RH implicit_p tag (<?rh-implicit_p ?>MyTextStringWithNoPTags); there's no telling who's more to blame for text that is missing <p></p> tags, the user or RH, but at least RH cleans up after itself. Unfortunately, Flare chokes up a hairball when confronted with this one.

Needless to say, you should spend the few moments to eliminate these in RH before you convert the projects.

The rest of your effort will be spent wrapping your mind around the different terminology and workflows between RH and Flare (this might seem easy enough, at first blush, but is not!). And merged projects can't take advantage of things like Search Filter Sets and Related Topic Links, so it's best if you create a three-project merged system for testing everything, and I mean everything, before you do your full conversion!


Good luck,
Leon