HTML publishing workflow using Technical Communication Suite and standalone products

Mixed sources of documents
Project-wide conversion settings
Tips for creating context-sensitive Help
- Scenarios for creating a project
- Scenarios for updating a RoboHelp project

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