HTML publishing workflow using Technical Communication Suite and standalone products

Adobe Technical Communications Suite provides technical communicators a streamlined workflow for authoring content once and delivering it in multiple formats. You can author in FrameMaker and import FrameMaker documents into RoboHelp to publish Help in several formats, including Adobe AIR Help and WebHelp.

The suite provides more features than the individual suite applications used as standalone products. The following table lists some differences in the workflow for importing FrameMaker documents when you use the suite and when you use the standalone products.

Task in the workflow

Technical Communication Suite

FrameMaker and RoboHelp as stand-alone applications

Importing FrameMaker documents into RoboHelp project

Link to or import the FrameMaker source documents into the RoboHelp project.

Import FrameMaker documents.

Synchronizing FrameMaker source files and RoboHelp topics

The Project Manager pod in RoboHelp indicates whether the linked documents are out of sync. You can update the linked documents to have the changes reflected in RoboHelp projects. You can choose to preserve the changes in the generated topics.

Reimport the FrameMaker documents and overwrite the topics generated earlier.

Updating the topic structure when pagination settings are changed

Update the FrameMaker document in RoboHelp.

Reimport the FrameMaker documents and overwrite the topics generated earlier.

Mixed sources of documents

Typically, you use the suite workflow to convert your existing FrameMaker books to online Help format; that is, you link the entire book into RoboHelp. If you have well-shaped FrameMaker documents, you can optimize the workflow with minimal changes to the FrameMaker source or generated topics in RoboHelp. Use this method when your author primarily in FrameMaker and want to use RoboHelp as the publishing tool.

However, sometimes it’s necessary to reuse content from diverse sources in RoboHelp projects. An example is updating a small online Help project by including conceptual information from a reference guide and troubleshooting information from a maintenance guide. Perhaps these documents are authored in different tools and templates, and perhaps they follow different writing guidelines.

Documents can have these sources, among others:

  • Documents authored in earlier versions of FrameMaker

  • Documents authored in structured and in unstructured FrameMaker

  • Documents authored in FrameMaker and in Microsoft Word

Project-wide conversion settings

RoboHelp allows you to define project-wide settings for each source type. For all FrameMaker documents, you define the conversion settings only once, whether they are linked to or imported into RoboHelp. Similarly, the conversion settings of Microsoft Word documents remain the same for linked as well as imported documents.

Project-wide conversion settings promote consistency not just in your project but across multiple projects. You can quickly set up a RoboHelp project without having to define individual conversion settings for paragraphs, tables, images, and so on.

Project-wide conversion settings work best when you author the entire document either in FrameMaker or in Word and use RoboHelp as the publishing tool. In this case, you simply optimize the source content for publishing to online Help formats and do little or no content modification in RoboHelp. However, if you have a mixed authoring environment or content from multiple sources, complex scenarios arise. Differences in the following can add complexity:

FrameMaker templates
RoboHelp allows you to select a template to be applied to the FrameMaker documents that you link or import. Different document types could have different templates with different paragraph and other formats defined.

Topic naming patterns
This complicating factor arises when you base the topic names on the paragraph text. Depending on how you have written the headings, the RoboHelp topics could have inconsistent names. For FrameMaker documents, you can define topic naming based on custom markers. You can’t define topic naming based on custom markers in Word.

Context-sensitive Help marker text
Defining context-sensitive Help in the source documents itself gives you complete control over how the online Help is created. However, defining context sensitivity in the source can introduce significant complexity. If you have multiple types of source documents, you usually have several types of markers that differ in syntax.

Tips for creating context-sensitive Help

To overcome the challenges, keep the following tips in mind when you plan your project:

Determine the workflow
If you’re working on a large RoboHelp project created natively, it makes more sense to continue authoring in RoboHelp if the content inputs are minimal. Linking and importing external documents can increase the complexity of the project, especially if you defined TOCs, indexes, glossaries, and context-sensitive Help settings in RoboHelp. If, however, you are creating a project from scratch or significantly revising an existing project, link to and import external documents to avoid updating content manually in RoboHelp.

Identify the source documents
Before you define the project settings in RoboHelp, identify the sources of content that you intend to use in your project. If all your source documents are well-shaped FrameMaker documents, link the documents. If your source documents are of several types, import the documents.

Explore your linking and importing options
Even though you can choose to convert the TOC, index, and glossary from the source documents, explore your options carefully. For example, importing a TOC works best when you want to retain the TOC structure in your source documents. Similarly, if you are importing a set of FrameMaker and Word documents in different versions, consider carefully before using context-sensitive Help markers or index markers. Their use is advantageous only if you are making significant revisions. If the update is minimal, sometimes the best option is to import the content and add the map IDs or index entries natively in RoboHelp.

Scenarios for creating a project

Source documents

Method to use

Options available

Single unstructured or Structured FrameMaker book

Link FrameMaker book

Use RoboHelp as the publishing tool, with little or no content authoring in RoboHelp
  • Define pagination based on either FrameMaker paragraph formats or custom markers

  • Create context-sensitive Help using custom markers in FrameMaker

  • Convert TOC, index, and glossary

Multiple unstructured or Structured FrameMaker books

Link FrameMaker books

Use RoboHelp as the publishing tool, with little or no content authoring in RoboHelp
  • Define pagination based on either FrameMaker paragraph formats or custom markers

  • Create context-sensitive Help using custom markers in FrameMaker

  • Convert TOC, index, and glossary

Single or multiple FrameMaker books in versions earlier than 7

Import FrameMaker books

  • Define pagination based on either FrameMaker paragraph formats or custom markers

  • Create context-sensitive Help using custom markers in FrameMaker

  • Convert TOC, index, and glossary

Independent FrameMaker documents

Import FrameMaker documents

  • Define pagination based on either FrameMaker paragraph formats or custom markers

  • Convert TOC, index, and glossary

Single Word document with a well-shaped TOC and index

Link Word document

  • Define pagination based on Word paragraph styles

  • Define context-sensitive Help marker using the custom footnote option in Word and use the marker text for context-sensitive Help

  • Convert TOC, index, and glossary

  • Use RoboHelp as the publishing tool, with little or no content authoring in RoboHelp

Multiple Word documents

Import the documents

  • Define pagination based on Word paragraph styles

  • Define context-sensitive Help marker using the custom footnote option in Word and use the marker text for context-sensitive Help

Mix of FrameMaker books and Word documents

Link FrameMaker and Word documents

  • Define pagination based on FrameMaker and Word paragraph styles, separately

  • Use context-sensitive Help marker in source documents

Mix of independent FrameMaker and Word documents

Import the documents

  • Define pagination based on FrameMaker and Word paragraph styles, separately

  • Use context-sensitive Help marker in source documents

Scenarios for updating a RoboHelp project

Source documents

Method to use

Options available

Single unstructured or Structured FrameMaker book

Link FrameMaker book

  • Define pagination based on either FrameMaker paragraph formats or custom markers

  • Create context-sensitive Help using custom markers in FrameMaker

Multiple unstructured or Structured FrameMaker books

Link FrameMaker books

  • Define pagination based on either FrameMaker paragraph formats or custom markers

Multiple FrameMaker books or independent FrameMaker documents

Import FrameMaker books and documents

  • Define pagination based on either FrameMaker paragraph formats or custom markers

Single Word document with a well-shaped TOC and index

Link Word document

  • Define pagination based on Word paragraph styles

Multiple Word documents

Import the documents

  • Define pagination based on Word paragraph styles

Mix of independent FrameMaker and Word documents

Import the documents

  • Define pagination based on FrameMaker and Word paragraph styles, separately

// Ethnio survey code removed