Not quite the integration I hoped for - or a complicated question

Report · Apr 16, 2008

Greetings,

I've been using Frame for over 10 years and Robohelp for about 6, on and off, for both of them; plus a lot of Interleaf, and several other DTP, word processing, and imaging/drawing apps... in short, I'm no neophyte in the tools and principles of technical writing.

I'm trying to single-source some related documents (online help, FrameMaker user's guide, and possibly a FrameMaker programming guide). The guides will be printed and delivered electronically, so a primarily-printed output is required.

So my client purchased the TC suite and handed me the assignment for these and several other documents. I've determined that the only shareable content will be procedures and definitions. So what I'd like to do is create source objects and put them in a shared directory. Procedures will consist of a heading and a numbered list, possibly images where appropriate. Definitions will consist of a heading and one or more short paragraphs of body text.

If I were just single-sourcing in FrameMaker, this would be a very simple structure to create and deploy. I would have host documents with their own, native, static content and create shared text references out of the content files mentioned in the last paragraph. All of the structure of the documents would be native to the host document.

However, it seems to share FrameMaker files with RoboHelp, it's a very one-way process, and not very modular. For instance, assume I want to make a topic out of one of my source procedure files. I import the file by reference into RoboHelp, and it appears as a new topic in my help system. That's great, but now I'd like to add a list of related links to the topic, or maybe some other additional blurb of content that I want to appear in the Online Help, but not in the FrameMaker documents. I can't do it. If I make changes to the imported Frame document, I can't later make changes to the Frame source file and update it without losing changes made in the help file.

The functionality I would really like (and if it's there, I cannot see it), is the ability to import a frame file as a text inset into RoboHelp exactly the way it is done in FrameMaker. That way if I have a boiler-plate paragraph shared definition that is only part of a topic, I can just insert it at the cursor's location and have a live link to the Frame source file for updating when needed.

Alternately, if FrameMaker could import an HTML file by reference, I could author my definitions and procedures in RoboHelp, then pull in the HTML files into FrameMaker just like I can do with Word document (or for that matter an imported graphic). There doesn't seem to be any reason why we couldn't go both ways. 95 percent of the functionality is already there, so I suppose it wouldn't be hard to go the next step. The same goes for the HTML snippets, which are a cool idea, but again, not compatible with FrameMaker: if FrameMaker could import an .hts file by reference, those handy snippets could appear in both Frame and RoboHelp files and be auto-updated easily.

As it is, I don't see any way to take advantage of all of this integrated functionality. The philosophy behind the design of the integrated RH/FM packages seems to be that I can create a Frame Book and turn it into a RoboHelp Help system, which would really make for a crappy, and fairly pointless help system that looks like a printed document. I can already generate a PDF out of FrameMaker that is technically usable online. What I really want is to be able to use much of the same content but put it online help system that looks and feels like an online help system.

Sorry I'm a long way into my head and not sure if any of this will make sense to others or not. I've been playing with single-sourcing in a lot of applications, so my way of thinking about it is kind of abstract and hard to follow without example.

Does anyone have any light to shed or anything else to share about single-sourcing methodology with the new package? Hopefully, I'm just missing something and what I want to do is doable.

Thanks in advance.

Tom

Report · Apr 16, 2008

As I understand it, the TCS uses RoboHelp as the (help) publisher in a
single-sourcing workflow from FM. If you use conditional text in the
FM documents, the conditions get passed to RH and can be activated (on
or off) as required. You still do all of your maintenance and writing
at the FM end in this scenario.

Report · Apr 16, 2008

As Arnis mentioned, you can use conditional text in FrameMaker to add Help specific content in FrameMaker. Since both FrameMaker and RoboHelp support conditional text, allow you to filter content and RoboHelp imports content with conditional text settings intact, this works.

You can also edit a part of content (a topic) in RoboHelp and preserve the changes in that topic while you update the remaining content from FrameMaker.

Report · Apr 17, 2008

Thanks Arnis and Jain for your replies. I'm familiar with context sensitivity and the role it plays in the FM/RH integration, but even with it, I'm still only part way to where I'd like to be.

I'm not trying to write a whole FrameMaker book and then single-source it into a help system. The printed guides and the help system might only share about 30 percent of the same content between them. But I would like the shared content to be single-sourced.

So let's say I have a descriptive paragraph that I want to use in the OLH and the Print docs. So I author it in FrameMaker as a separate document and import it into my two printed documents by reference, within the larger context of those two books. But in the OLH version, I want that one paragraph, along with its heading, to be either

• part of a bigger topic
• a separate topic with some related links at the bottom, or
• (better yet) inserted into a table cell because all of my OLH topics are a two-column table with related links in the right column and body text in the left column.

I can't really do any of these. If I import the frame file by reference, it wants to be a whole topic. Any subsequent changes I make to that topic will force me to either break the ability to update with changes from the source document or accept that any changes to the Frame source document will destroy the changes made in RoboHelp.

If I put a list of cross-references in the Frame topic, then condition them for the OLH only, those could turn into my related links, but it will only work if the targets of the cross-references were inside of the same Frame book to begin with (I can't create a reference from within Frame to a RoboHelp topic that was natively created in RH.

On the other hand, if RoboHelp could just import a Framemaker document by reference as a text inset, the same way as Frame does it, it would be perfect. I could add material within the topic before or after the inset, then still update the inset whenever I made changes to the source.

Again, maybe I'm just missing something, but it doesn't seem like there's any reasonable way for me to do what I need to do with any single-sourcing.

mrtomh

Report · Apr 17, 2008

quote:

Originally posted by: mrtomh@yahoo.com
I'm not trying to write a whole FrameMaker book and then single-source it into a help system. The printed guides and the help system might only share about 30 percent of the same content between them. But I would like the shared content to be single-sourced.

Tom,

although at the first look your reasons are understandable, IMO your way would really make issues more complicated. Trying to integrate and mix content from two different sources is always more difficult (and error-prone). It is easier for writers to work with a single editor for all content, it is easier to exchange content. For instance, if some sections you originally thought would be in the help file only, suddenly are supposed to be available in the printed documents as well?

I always found it easier to write in a 'printable' environment which by design can handle all the special issues involved when creating 'books' (like pagination control). When pushing such content through a conversion engine to HTML it is easy to throw away the special things that are only needed for print output. The other direction is not as easy; it is very difficult to automatically add good pagination.

Also with FrameMaker you can easily set up two (or more) books which share a certain amount of common sections.

If the percentage of common content is really low, you might want to look at other editors, but I would alway advise to work from a well-defined, single source format with one editor.

- Michael Müller-Hillebrand

Report · Apr 17, 2008

mrtomh,

IT sounds like you're really aiming to do topic-based authoring as in
a DITA documentation model. This way you assemble all of your discrete
topics using map files (kind of similar to FM's book-building) to get
the final piece. The publisher route for creating the actual
deliverable would be a bit different though - you'd probably have to
use the DITA Open Toolkit (OT) to create the help files.
Alternatively, you could possibly create a Book file in FM from the
specific map and then publish that through RoboHelp (haven't heard of
anybody doing that though).

Regardless of the route, with the current set of tools, it's going to
be convoluted.

RoboHelp does utilize "snippets" which are similar in concept to FM's
text insets. Unfortunately, you can't link these to FM files to
maintain a dynamic single-sourcing workflow. There's an Adobe devnet
article on these at
http://www.adobe.com/devnet/robohelp/articles/snippets.html that might
be of interest.

Report · Apr 17, 2008

Arnis,

Thanks for your input. You're right about my aims. Using just FrameMaker, it is quite possible to do topic-based authoring with text insets, conditional text, and variables. I've seen and created very dynamic product that way. I was hoping that the TC suite would extend FrameMaker's existing functionality into RoboHelp, but it stopped a little short. It was worth a try to see if anyone discovered something other than I did in playing with the new suite. I did see the RoboHelp snippets (and I read the article you linked for me) and I think they're a great idea for developing help systems. Too bad they didn't make FrameMaker able to import an HTML (and/or .hts) file as a text inset: map the HTML tags to Frame paragraphs, etc. That might have been another fairly streamlined way to share content between the two applications.

I don't really have the option of bringing in other development tools, so it sounds like I'm stuck doing things the old way with the new package.

Tom

Report · Apr 17, 2008

Michael,

Thanks, you make some interesting points worth considering. I'm going to have to do a little more thinking on it and maybe a little experimenting to see if I can author the help system in Frame (making use of the content-sharing available exclusively in Frame with the other two documents), then pull the whole system into RoboHelp.

Tom

Report · Apr 17, 2008

Tom

Have you explored FrameSets in RoboHelp? You can add multiple topics in a FrameSet. Since you maintain your HTML content in a table structure, will FrameSets help?

Report · Apr 18, 2008

Jain,

Thanks for the suggestion. I haven't touched a frameset since my early homepage authoring days. Since your post, I've been playing around with the idea, and it just might work. It could be a pain to setup the whole system, but I can use one of the frames in the frameset to pull in the imported FrameMaker .fm file.

I'll keep you all posted.

Tom

Report · Jul 17, 2009

All,

Another loose end I might as well tie up as long as I'm here.

I regret to report that everything I tried from my own bank of ideas and from the ideas of others in this forum ultimately failed to produce the result I was looking for (or even a close enough). The numerous shortcomings of the Frame-to-RH single-sourcing engine ultimately overcame my will to keep coming up with workarounds. I was using a Frameset model for quite some time, and it almost worked... almost. I have a long s***... er laundry list of things that could have been done better, some of which I've described in earlier threads.

But anyway, here is what I ended up doing instead:

1. Copied all of my FrameMaker content into RH as new topics.

2. Threw away all FrameMaker source content and all remnants of the Frame stuff imported by reference.

3. Created two single-sourse layouts, one was WebHelp, the other a printed document.

4. Conditioned out of the print document layout:

a. The CSH topics from the webhelp

b. Any and all content that made reference to the online help.

c. The "Related Topics," which were manually created hyperlinks at the bottom of each webhelp topic.

5. Conditioned out of the WebHelp output layout some printed-document-only content.

6. Output the WebHelp according to a typical process.

7. Created a Word template with all of my FrameMaker styles defined in it (same exact names).

8. Mapped the RoboHelp styles to Word Document styles (Except for Heading 1, etc. which apparently absolutely have to keep those names).

9. Generate the Printed (Word) doc.

10. Used Word's capabilities to do global search and replace for niggling formatting issues.

11. Created a FrameMaker book with a front matter, TOC, body chapter, and back page. The book has my typical printed document catalogs in it.

12. Copy and paste the entire reformatted Word document into the FrameMaker body chapter (not linked, just copied).

13. Used FrameMaker tools to make any final tweaks to the Frame version. A particular hassle was I had to change the anchored frame properties for every screen capture because they come into FrameMaker as floating anchored frames that end up in bad locations (I always use "below current line" and a figure title that goes above.

14. Generated the FrameMaker TOC.

15. Published the FrameMaker book to PDF for distribution online and P.O.D.

An obvious problem is that there is no live link between the printed doc and the online help. The whole process is a one-way process. When I need a new printed User's guide, I have to re-output the printed doc, paste it into the word template, tweak it, copy it into the FrameMaker book, tweak it, then I'm done. Fortunately, I have it down to a pretty smooth process that takes about 30 minutes.

The final result, I can create a FrameMaker-quality (with appropriate company template) printed document from an online help project in less than an hour. If I had to do another new book rather than this same project, it would take a little longer because I'd have to create a new Frame book and monkey with the front and back matter, etc., but overall it isn't that hard to do.

It's nowhere near the solution I was looking for, but it works.

I hope this description is helpful to some of you struggling with this kind of issue.

(I know TC Suite 2 will probably eliminate the Word step, making it that much easier, but I don't have that yet.)

Cheers,

Tom

Report · Jul 17, 2009

Hi Tom,

I've been trying to follow what you're trying to accomplish in this thread & having a great deal of difficulty.

Why all this back & forth stuff to Word & FrameMaker from RoboHelp?

I thought that the whole idea of single sourcing is that you do ALL of your writing in Frame; creating separate books for print & online versions out of the common .fm documents that make up the components of each. You say there's only about 30% common material between the two - fine! Use text insets for that stuff and author away. It's a one-way street from FM to RH.

When it's time to publish - suck the online FM book into RH and print your PDF from FM for the printed material. What's the big deal? There's no need to screw around stripping "printed" references out of the topics in RH - they're already gone because they never existed in the FM doc in the first place, right? I think your mistake is trying to print PDF's out of RH - it's not a very good tool for that compared to FM IMHO.

I don't know, maybe I've just misunderstood what you're trying to accomplish.

Jeff

Report · Jul 17, 2009

Thanks for the comments, Jeff.

I agree that the method I'm using begs for the questions you ask. I would have much preferred a simpler solution such as text insets for shared content, then pipe a Frame file or book into RoboHelp for online help publishing (I'm paraphrasing, but I think that's basically what you suggested).

My basic goal is to create a typical online help system with context-sensitive topics and concept/procedure based topics combined to make a complete help system. Like all help systems, I need there to be sufficient navigation from the TOC but also interlinking of topics (via the common "Related Links" or "Related Topics" approach.)

At the same time, I would like to present the concepts and procedures (at least many of them) in a printed or printable format that can be ordered print-on-demand or downloaded from the web (a User's Guide). The printed doc should look like it other printed documents we produce with FrameMaker.

I originally started out with a Frame-centric method with text insets, multiple books (one for the print output, one for importing into the online help), but in addition to many annoying limitations, there are three significant problems and one show-stopper.

1. Importing bulleted and numbered lists from FrameMaker to RoboHelp just plain blows. I know there are some workarounds and proper ways to do it that make it work almost like you would like it to, but even if I wanted to do that, I find that I can't condition off a paragraph with a bullet or number in RoboHelp... it leaves 1 or two blank lines and sometimes a bullet. Imagine a procedure in a text inset where I want to condition out a step that makes no sense to the user who already has the program open. I can't do it.

2. Graphics conversion from FrameMaker to RoboHelp is terrible. I did have a workaround for it (I described it in another thread), but it was clunky, a lot of work, and still didn't look very good. In retrospect, I don't need a lot of graphics in my online help compared to what's in the printed doc, but there are a few and it is hard to make them work and look anything close to professional.

3. (this is the show stopper). There is almost no way to create my Related Topics section at the bottom of each topic. Actually I did find a way that almost worked, but it meant I had to create Framesets and use them as wrappers for the actual imported topics. Then I would put the Related Links section in a separate frame and the hyperlinked topics could be made and edited. It's hard to describe. It was a lot of extra work (1 frameset, 1 imported topic, and one additional html file for the related topics for each "page" of the inline help that came from a FrameMaker topic. But there was no way to make the lines between the nested frames invisible, and there was no way to let put a print button for users that would actually work the way you'd expect.

Maybe you know some tricks I don't, and if so, please share them. I've been playing with this project for over a year and I think I've explored every possible way to do it, documented or undocumented. Compared to the other options I explored, the final method I'm using is much easier, less complicated to understand, and meets all of my objectives. Please let me know if it still doesn't make sense.

Regards,

Tom

Report · Jul 17, 2009

Hi Tom,

Wow - that's sounds really complicated all right!

I'm just starting out in my company's project of shredding apart all of our Word docs (distributed as PDF's) and putting them into a new order in FM.

We're using TCS 2.0. Our unstructured FM docs get imported (not linked - RH crashes when I try to do that) into RH for the creation of Webhelp and a .CHM (maybe - CHM doesn't look "new" enough to the managers, so that part may not happen).

I've got lots of bullets and numbered lists in the Frame docs and haven't been bothered by any differences between FM and the Webhelp output - that may be due to the work we had done by a consultant in creating a customized fmstyles.css, but I don't know enough about css's to be able to tell. I don't do any further conditioning in RH except telling it when generating the Webhelp to exclude the Comments, Print, and PrintOnly conditions from FM. They're still in my FM docs because they're going to be used for creating PDF's for printing (again, maybe, only if someone wants it).

I haven't started dealing with screenshots and graphics in my Frame files yet. After reading a bunch (these forums, the FrameUsers list, Free Framers list, and Art Campbell's TCS Google Groups list) I think I'm going to have problems. Right now I've left space in my Frame docs with anchored frames for them to go & have conditioned them to be PrintOnly. The online Webhelp format doesn't need many screens for the moment and I may try using some sort of DHTML effect for them to pop out when I need them - work still to be determined ;>)

I don't have any of those Related Topics things in my Webhelp, but I do have a whole whack of cross-references to other topics that I created in FM and that came over fine to RH. What you describe sounds pretty fancy!

Maybe some day I'll get up to your level - I think I need to take some courses or something...

Jeff ;>)

Report · Jul 17, 2009

Jeff,

I'm not going to get the TCS 2.0 anytime soon unless I want to pay for it out of my own pocket, but based on what I've seen, it will solve some problems. The bulleted and numbered lists are supposed to be greatly improved, and I hope they fixed some of the other stylesheet-related problems. I haven't heard one way or the other about the problems with graphics. There is a good argument that you shouldn't need a bunch of screen captures in an online help, but there are good reasons to have some.

You will learn a lot just by doing what you're doing if you're curious and diligent. I've been working with FrameMaker on and off for over 10 years, RoboHelp for about 5. They're both good, but I always seem to find way to push them to their limits and then get disappointed when they don't do what I think they should do.

Anyway, good luck!

Tom