Skip navigation
Currently Being Moderated

Technical documentation

Jan 24, 2012 1:14 AM

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

 
Replies
  • Currently Being Moderated
    Jan 24, 2012 7:06 AM   in reply to Vincent-Sweden

    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.

     
    |
    Mark as:
  • Currently Being Moderated
    Jan 24, 2012 8:44 AM   in reply to Vincent-Sweden

    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.

     
    |
    Mark as:
  • Currently Being Moderated
    Jan 24, 2012 10:00 AM   in reply to gsmith9810

    ... 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?

     
    |
    Mark as:
  • Currently Being Moderated
    Jan 24, 2012 2:05 PM   in reply to Error7103

    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.

     
    |
    Mark as:
  • Currently Being Moderated
    Jan 25, 2012 4:39 AM   in reply to Vincent-Sweden

    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.

     
    |
    Mark as:
  • Currently Being Moderated
    Jan 25, 2012 7:29 AM   in reply to Vincent-Sweden

    Vincent - In my earlier situation the 200+ manuals were each for unique products. My group only had a half dozen products. Those documents did use some common paragraphs.

     

    We used Structured FM v7 there. We were unable to use the most current version due to incompatibilities with other s/w.

     

    Currently I'm using (unstructured) FM v10 in support of a single system. Quite a lot of material was migrated into the book I'm working in from earlier work (in FM) however the styles and formatting required in this new book differ from the earlier material.

     
    |
    Mark as:
  • Currently Being Moderated
    Jan 26, 2012 7:04 AM   in reply to Vincent-Sweden

    say... 10 languages, there will be a heck of a lot of text with different languages in one set of file... is that really a good idea?

     

    If the author is not the translator, and the translators need to work on the document at the same time, then it is definitely not a good idea. If the author is the translator, it becomes a matter of personal preference. It's just one way of doing it.

     

    We send our manuals out for translation, so my experience is limited to versioning by market region (both English) and by badge engineering (still English, but different page layouts and much content unique to each brand).

     

    Frame can apply conditions to anchors, letters, words, sentences, paragraphs, pages, chapters ... basically any level of granularity that you desire. So the translations can be in the same text, or not. I'm not aware, however, of any feature to flag the other language blocks if one is changed.

     

    >> One way to manage the 60 versions is to set up 60 mostly-empty books.

     

    The master book might be:

    • draken.book
      (no edits once set up - just a container and menu)
    • drakenFRONT.fm
      (generic cover not specific to any model)
    • drakenTOC.fm
      (Table of Contents - a generated file, usually needs no edits after setup)
    • drakenBODY.fm
      (the master content flow for all editions)
    • drakenIX.fm
      (Index - a generated file, usually needs no edits after setup)
    • drakenBACK.fm
      (generic cover not specific to any model)

    You confine almost all of your edits to drakenBODY.fm. You probably never render or print from this file set itself.

     

    If you prefer separate master files by language, you'd have three sets of the above (with different names).

     

    A typical model-specific book (one of 60) might be:

    • J35A.dan.book
      (No edits once set up, which can include the PDFinfo. This is just a container and menu. You set Condition Codes book-wide to turn off all language content except Danish, and all model-specific content not applicable to the J35A.)
    • J35A.dan.FRONT.fm
      (Rarely edited once set up. Uses drakenFRONT.fm as template, but has unique content and is commonly the master file for model-specific Variable settings, such as Pub.No., and other header/footer content. Variables are imported from here to all other .fm files in the book.)
    • J35A.dan.TOC.fm
      (Table of Contents - a generated file, usually needs no edits after setup)
    • J35A.dan.BODY.fm
      (Uses drakenBODY as template. The only content is a text inset of the entire Flow A from drakenBODY.fm. You never edit this clone of the Flow in this file.)
    • J35A.dan.IX.fm
      (Index - a generated file, usually needs no edits after setup)
    • J35A.dan.BACK.fm
      (Rarely edited once set up. Uses drakenBACK.fm as template, but has any unique content desired, plus model-specific content from Variable settings)

    You basically only render PDFs or print from any of the model-specific books. Once set up, the files never need editing, other than to touch copyright dates or other boilerplate periodically. I do this today for import/export and alternate brandings, and it works. TOC and IX files are automatically updated in an Update Book operation.

     

    In the scripting approach, using the FrameScript standard in FM10, you only have the "draken...." master files, and no model-specific working files. You have 60 scripts. Each script sets variables and condition codes in the master "draken" files, updates the book, and renders the localized and model-specific output required. I don't have FM10, and have not tried this.

    _____

    I might add that Frame Condition Codes can have indicators (decorations like color, underline, etc.) that are visible only during edit. For example, we use blue text for North America-specific content, and Orange for EU-specific. The indicators (decorations) are switched off for rendering, during the setting of Conditons for the editions.

     
    |
    Mark as:
  • Currently Being Moderated
    Jan 26, 2012 6:57 AM   in reply to Vincent-Sweden

    In my former situation our writers would check-out the master *.fm files from Idiom's WorldServer CMS and work locally.

     

    Typically they were working in a chapter file. Optionally they would be working in a shared file containing common/boiler plate material that would be opened/edited/saved and then subsequently pulled in by reference to chapter files.

     

    Our authors were not the translators.

     

    WorldServer contained subfolders that contained duplicate files used by the translation team. The translators were never working with the master chapter files.

     

    They were able to subsequently see any edits the primary authors made.

     

    We tried to schedule the work so that the authors were essentially frozen as far as content authoring went. Edits were allowed to deal with bug fixes and or last minute changes. The intent was to minimize the ripple effect.

     

    During the translation process we we had a system set-up whereby we'd get clarification questions from translators and we'd get a response out to them within 24 hours.

     
    |
    Mark as:

More Like This

  • Retrieving data ...

Bookmarked By (0)

Answers + Points = Status

  • 10 points awarded for Correct Answers
  • 5 points awarded for Helpful Answers
  • 10,000+ points
  • 1,001-10,000 points
  • 501-1,000 points
  • 5-500 points