• Global community
    • Language:
      • Deutsch
      • English
      • Español
      • Français
      • Português
  • 日本語コミュニティ
    Dedicated community for Japanese speakers
  • 한국 커뮤니티
    Dedicated community for Korean speakers
Exit
0

Technical documentation

Explorer ,
Jan 24, 2012 Jan 24, 2012

Copy link to clipboard

Copied

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

Views

2.1K

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Community Expert ,
Jan 24, 2012 Jan 24, 2012

Copy link to clipboard

Copied

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.

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Explorer ,
Jan 24, 2012 Jan 24, 2012

Copy link to clipboard

Copied

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.

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Community Expert ,
Jan 25, 2012 Jan 25, 2012

Copy link to clipboard

Copied

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.

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Explorer ,
Jan 25, 2012 Jan 25, 2012

Copy link to clipboard

Copied

I'm having a little hard-time understanding and commenting on your detailed post, I'll do my best comment, so bear with me.

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

In my head I'm imagining a flow of text, like word document. In there, teach text/paragraphs is translated but it is in the same file. If I expand the language content, 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?

In Arbortext, the text is determined in blocks. These blocks, may contain 1 sentence to 10 parapgrahs, could be an entire chapter. The orignal block is then connected to another blocks (using conditional sets), say another language. If I change the original block, all of the other blocks, connected with the orignal one, will raise a red flag, telling me to either change the other languages or accept it.

"Interleaved language is probably not ideal if multiple writers work on the same manual at the same time."

Thank god this is not a problem at the moment.

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

I understand each sentence, but I can't wrap my head around the entire paragraph...

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


I understand, but I'm having difficulty visualizing this...

Do you have a link that I can read up on or a ebook/book that you can recommend?

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Community Expert ,
Jan 26, 2012 Jan 26, 2012

Copy link to clipboard

Copied

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.

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Guest
Jan 24, 2012 Jan 24, 2012

Copy link to clipboard

Copied

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.

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Community Expert ,
Jan 24, 2012 Jan 24, 2012

Copy link to clipboard

Copied

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Guest
Jan 24, 2012 Jan 24, 2012

Copy link to clipboard

Copied

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.

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Explorer ,
Jan 24, 2012 Jan 24, 2012

Copy link to clipboard

Copied

And you guys use... frame maker?

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Explorer ,
Jan 24, 2012 Jan 24, 2012

Copy link to clipboard

Copied

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

These 200 software manuals. Are they completely different from each other? Do you resue the text (Paragraphs)

My problem is that, some paragrapsh containing, say 4 sentences. I sometime need to change minor things in that paragrpahs, singular to plural, or changing a number from 50 to 60, etc...

Let's say that the company I' working for haven't really designed the products to be consistent (to have a basic design for specific serie, functionality etc...), ppl never thought of technical documenation when they started 10 years later... My world looks like below... but far complicated.

2012-01-25 07-49-54.png

//Vincent af Sweden

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Guest
Jan 25, 2012 Jan 25, 2012

Copy link to clipboard

Copied

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.

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Explorer ,
Jan 25, 2012 Jan 25, 2012

Copy link to clipboard

Copied

But you did not deal with different languages, right?

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Guest
Jan 26, 2012 Jan 26, 2012

Copy link to clipboard

Copied

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.

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Explorer ,
Feb 08, 2012 Feb 08, 2012

Copy link to clipboard

Copied

LATEST

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

Votes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines