Looking for help system strategy and technology

[Rantamäki Annu <annu -dot- rantamaki -at- dosetek -dot- varian -dot- com>]

Hi everybody,

I would like to ask your opinions on our situation or experiences of similar situations. This is a very long message so please be patient. Thanks.

About 1.5 years ago, our company decided to develop our first online help system. Up until then, we had only created printed manuals and PDFs. The original plan was to go for single sourcing, modularize the contents and keep it in a database (XML was mentioned a few times). We also wanted to give up all printed documentation, with the exception of "quick start guides". As an intermediate step, we agreed to use FrameMaker 6 for managing the modules and translations (6 languages) and for producing the PDFs. ForeHelp was our selected HAT. We thought this intermediate step would provide our customers a smoother transition to completely electronic documentation and that it would be a flexible solution for the future. A few months into the project, a decision was made to switch from ForeHelp to Robohelp 2002, not entirely by our choice.

Writers in two locations in two countries participated in the creation of this help system. There was me, a company employee working alone in one country, and a contractor company with 2-5 writers in another country. The contractors designed the help system and the transition from PDFs and printed publications to an online system and also otherwise lead our project. Our product is a suite of software applications developed in different countries.

In the end we ended up with two implementations of the help system design:

1. The contactors created a FM file structure where each part of the software was described in two files: the first file contained the conceptual topics, and the second file contained the procedural topics. The files were imported into RH and further maintained there.

2. I created a more complicated FM file structure because I wanted to be able to provide our customers with similar PDFs as before. In this case, the content of the PDFs (7) and the help were partly overlapping. The information was broken into chapter files, text insets, and within these conditional text. However, text insets were created only where necessary-e.g., all procedures were not saved in separate files, only those that actually were used in several places. One of the PDFs consisted completely of small text inset files. The files were imported into RH but maintained in FM. Changes were made to the FM files, of which the changed part was re-imported into RH, and the linking re-created in RH. Linking was not created in FM because the help design required procedures to open in a secondary window, which was not possible to define in FM. The index was created from the index markers in the FM files; TOC was created in RH because the structure of the help was different from the PDFs, like a merge of the PDFs.

Towards the end of our project, the contractors, who were also responsible for the translations, saw that the initial idea of FM modules was not the best solution because our main goal was a functioning help system, not PDFs. Our focus is on error-free creation and maintenance of the help system, and PDFs can be created from any source, even from RH. Moreover, the FM-RH import proved to be unreliable, and building complete local language online help systems too time-consuming. In addition, managing and handling of updates would have been difficult.
As a result, the translators took the HTML files, processed them in Trados, which provided a good way of identifying and keeping track of the information, and exported the translated text in HTML. Rebuilding and the verifying the local language HTML help system was consistent and reproducible this way. Updates can also be done efficiently. The two-file system was re-desktopped from the translated HTML sources to produce the corresponding PDFs and the "quick guides", which was easy enough.

The contractors considered my FM file system too complicated for producing the language help versions, so these files were processed in the same way as their own simpler files. The PDF that consisted of FM text insets was translated by converting the text insets into normal text and processed separately to guarantee consistency and to avoid confusion with internal markers, conditional text etc.

An additional regulatory requirement has been brought up recently, namely to be able to review and comment the information using change tracking. Acrobat is considered too expensive, and so is FM. We've been presented views stating that FM is unnecessary or even a handicap where issues like flexibility, easy access, handling of complex local language systems, online help and media-independent publishing are concerned. In any case, the documentation source should be in a form that allows unlimited publishing and use of the documentation modules throughout the company. One of our guesses is that this could be achieved by starting true single-sourcing using XML. Since the current help systems are in HTML, and since FM is also capable of producing XML output, the contractors expect the transition to XML to be fairly effortless.

What is your guess? Which path should we take from here onwards? I have been reading the archives and seen that FM and Webworks has been recommended several times. How do they work in a multi-language environment like ours? Would they provide us a good transition to XML in the future? What are your experiences of Arbortext; could we move to their products? Any comments are appreciated.

Thank you very much,
Annu

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Order RoboHelp X3 and receive a $100 mail-in rebate, plus FREE 
RoboScreenCapture, WebHelp Merge Module and iMarkupSoftware, for a total 
giveaway value of $473! Order here: http://www.ehelp.com/techwr-l

   Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.