Skip to main content
Vincent-Sweden
Vincent-Sweden
Known Participant
January 24, 2012
Question

Technical documentation

  • January 24, 2012
  • 3 replies
  • 2407 views

My job is to maintain and develop user's manual for 20 different machanes, which is currently produced for three different languages and more will come. I have looked at different systems to manage this in one go, amongs them are Arbortext CMS, Indesign with XML-language and a custom CMS. I just discovered that Frame maker is a viable option. I read up on the software and its capabilities, but what I can't find is how it is used in technical documentation.

As I mentioned we have 20 machines, some of the content intersect with each other, meaning I have to have a super memory to know what that text is current and not current in which manual, and then update all or some of them.  Can Frame maker keep a track on what text/data is used in which user manual?

We have currently three languages, and are expanding. I can't manage more than 3 languages, even two is a headache. Do Frame maker have a specifik version support for languages or are there any proven/efficient methods to use Frame maker to manage 2+ different languages for users' manuals?

I have tons of questions and I have probably forgot to mention some info, but i gotto start somewhere.

Feel free to ask any question that can facilitate your answer.

//V

    This topic has been closed for replies.

    3 replies

    Vincent-Sweden
    Vincent-SwedenAuthor
    Known Participant
    February 8, 2012

    Thank you all for taking your time to provide me with real cases of using FM. I just installed the trial version FM 10 and will start to build a structure and see how far I can take this, based on your comments.

    I will problaby need to some help along the way, yoroshiku onegaishimasu.

    //Vincent

    A
    Anonymous
    January 24, 2012

    In a previous position we used FM to document 200+ s/w products and we released our documentation simultaneously in 13 languages annually.

    We used a lot of shared content.

    We used Idiom's WorldServer as out CMS which allowed separation of files enabling translation of copied files while authors worked in the originals.

    Bob_Niland
    Community Expert
    Bob_NilandCommunity Expert
    Community Expert
    January 24, 2012

    ... enabling translation of copied files while authors worked in the originals.

    Which raises another question for the basenote poster:

    How many writers work on one 20-product 3-lang manual suite at a time?

    A
    Anonymous
    January 24, 2012

    We had 12 geographically dispersed writers year-round with another dozen translators tapped into things for approximately two months a month or so prior to our release.

    Bob_Niland
    Community Expert
    Bob_NilandCommunity Expert
    Community Expert
    January 24, 2012

    My job is to maintain and develop user's manual for 20 different machanes, which is currently produced for three different languages and more will come.

    Are these released as one manual, three manuals by language, 20 multi-lingual or 60 manuals?

    ... some of the content intersect with each other, ...

    Frame can handle that with Conditonal text. Frame 10 has conditional expressions, so it's not even limited to the classical annoyance of "display if any true".

    We generate domestic and export versions of the same manual using conditionals, with conditions interleaved down to the character level as needed.

    To generate multiple editions, perhaps the easiest way is to set up an empty manual for each edition (with it's own pub number, headers, footers), and import by reference ("text inset") the entire flow from the master/authoring edition. Condition codes in each edition automatically switch off content/languages inapplicable to the present edtition. With some attention to cross-references, it works transparently.

    Vincent-Sweden
    Vincent-SwedenAuthor
    Known Participant
    January 25, 2012

    Are these released as one manual, three manuals by language, 20 multi-lingual or 60 manuals?

    No, they are all seperate user manuals. Everything is done in indesign.

    About 50-60 manuals

    Frame can handle that with Conditonal text. Frame 10 has conditional expressions, so it's not even limited to the classical annoyance of "display if any true".

    We generate domestic and export versions of the same manual using conditionals, with conditions interleaved down to the character level as needed.

    To generate multiple editions, perhaps the easiest way is to set up an empty manual for each edition (with it's own pub number, headers, footers), and import by reference ("text inset") the entire flow from the master/authoring edition. Condition codes in each edition automatically switch off content/languages inapplicable to the present edtition. With some attention to cross-references, it works transparently.

    I need to take a look at this "Condtional text feature" and the "text inset". I haven't start using the FF yet, but I reckon working in it is very different from any other word priocessing software/ desktop publishing software...is the system similiar to arbortext? Can't find anything that explains it properly...

    //Vincent af Sweden.

    Bob_Niland
    Community Expert
    Bob_NilandCommunity Expert
    Community Expert
    January 25, 2012

    I need to take a look at this "Condtional text feature" and the "text inset".

    Let's suppose one writer is responsible for 60 Draken manuals: 20 configurations, 3 languages.

    You can do this as one master manual, consisting of perhaps 5 component files: cover, TOC, body, IX (index), back cover, and 60 render-only shell manuals. Or you could use scripting to render 60 editions from the single master.

    The master Body.fm file contains one flow of text. Paragraphs are alternated by language. Each is tagged with a Condition Code, say Swedish, Finnish, Danish. When you switch any two of those off, only one language is visible for PDF and print rendering. Interleaved language is probably not ideal if multiple writers work on the same manual at the same time.

    Topical content can further be tagged by applicability, say with names like J35A, J35B, SK35C, etc. With conditional expressions, you can switch any combinations of these on or off.

    One way to manage the 60 versions is to set up 60 mostly-empty books. Each has its unique combination of Condition Codes preset. The cover/TOC/IX/end files are unique (with much content controlled by Variables, such as the 60 Pub. Numbers). The Body.fm file for each, however, consists entirely of a single text inset from the master Body.fm (this is an object imported by reference). Automatically, just the content of interest in the present edition is visible, rendered and printed. The 60 files, once set up, never need editing - just update and print. We do this today on a smaller scale, with import vs. export editions, and Division A vs. Division B badged versions of the same product (different manual templates, same shared/conditional content).

    Another way to manage the 60 is to use FM10's scripting capability. Set up 60 scripts to re-cast the master document to display only edition desired, and print. I don't have FM10, and haven't tried this yet.

    Text insets can be plain text or formatted text, with or without the source formatting. This feature can further be used to re-use content between different master manuals. There are limits on embedded cross-references, however.

    Terms & ConditionsAccessibility statement
    Using the community Terms of use Privacy Cookie preferences Do not sell or share my personal information ad choicesAdChoices