In my last post, I discussed ways that you can build lists of related links in your MadCap Flare projects. I expressed a preference for concept links.

If you share my enthusiasm for concept links and are importing FrameMaker content into Flare, you may want to pre-configure your source FrameMaker files to include Passthrough markers with special strings. When you import the marked FrameMaker content into Flare, the Passthrough markers convert to concept markers in the equivalent Flare topics.

You can then insert a concept link help control in each topic that contains the same marker and build a dynamic list of related topics. I described this process in the following post:

MadCap Flare Tip: Helping Users Find Related Information

When preparing your FrameMaker files to include Passthrough markers, follow these steps:

1. Add a custom Passthrough marker to each FrameMaker file. If you’re not sure how to set up markers in FrameMaker files, read this post:

   Preparing FrameMaker Files for Importing into MadCap Flare

2. Insert a Passthrough marker in the heading of each topic that is related to the same concept.
3. Add the following string to the Passthrough marker definition:

   <MadCap:concept term=”term” />

4. Substitute “term” with your concept term, keeping the quotes (“”). Make sure that “MadCap” has an uppercase M and uppercase C.

To ensure that the markers convert properly, enable the following Flare import settings. If you’re using an import file in your project, you’ll find these settings on the Options tab:

• Enable ‘Passthrough’ Markers = Checked
• Passthrough Marker Format = XML

Back to top

I haven’t written a post about MadCap Flare for a while, and the release of Flare 6 deserves special attention. With this version, Flare remains miles ahead of its competition.

When a new version of Flare is released, I usually install the new version and keep the last version installed, too. After testing the rock-solid Flare 6 beta during the past few months, I was easily convinced that I could fully upgrade on the GA release date. Flare 5 is no longer on my laptop.

I recently created Flare templates for the National Cancer Institute’s Center for Biomedical Informatics and Information Technology (NCI CBIIT). The Information Development team currently uses Adobe FrameMaker and Quadralay ePublisher. Lately I have been busy preparing Adobe FrameMaker files for import into Flare, running import routines with various settings, and testing the results.

I recommend the following process for preparing your FrameMaker files before importing their content into MadCap Flare. I will provide additional advice and tips in upcoming posts.

1. Back up your FrameMaker files.

Read this aloud: Create a backup copy of your FrameMaker files. You’ll need to alter them for an optimal import, so work with a copy—not with the original.

2. Remove formatting overrides.

Regardless of the tool you’re using to develop and publish information, you should use styles (called tags in FrameMaker). Styles automate the formatting process and ensure consistency.

Examine your FrameMaker files and make sure that they’re free of inline formatting created with the Formatting toolbar. In FrameMaker parlance, this type of formatting is called an override. In Microsoft Word, it’s called direct formatting.

I will provide advice on style mapping between Frame and Flare in an upcoming post. I have already included some advice on cleaning up your styles in a previous post. For more information, read the first of my six articles on Flare print publishing.

3. Add indentation to TOC sublevels.

A typical table of contents uses indentation to represent a hierarchy. In a Flare TOC, book icons are flush with the left margin, and topics and subtopics are indented.

Before importing a FrameMaker book, make sure that the FrameMaker TOC sublevels are indented. Flare relies on this indentation to properly create an equivalent TOC.

You can do this for FrameMaker TOC styles (levels 2 and below) by setting a property on the Basic tab of the Paragraph Designer:

1. Select the following menu command: Format > Paragraphs > Designer.
2. In the Paragraph Tag list, select the tag you want to change (for example, Heading2TOC).
3. Click the Basic tab.
4. Set the First property to a specific value. For example, a Level 2 TOC heading might be set at .25 inches, and Level 3 might be set at .5 inches.
5. Click Apply.

4. Predetermine the file names in your Flare project.

FrameMaker is a linear writing tool. Flare is a topic-based writing tool. When writers who are used to authoring in Frame first switch to Flare, they sometimes become disoriented in Flare’s authoring environment. Although Flare generally does a good job of naming topic files, the names might not always be what you expect.

To ensure that you can find your content in Flare, add a custom Filename marker to each of your FrameMaker files. You can then add this marker to FrameMaker chapter names and topic headings. During import, Flare creates a file for each chapter introduction and topic using the name that you pre-assigned.

Example:

• Let’s say that a chapter is called Browsing Terminologies. You insert a Filename marker in the chapter name and define the marker as intro_browsing_terminologies. (I typically prefix chapter introductions with intro. They also serve as section introductions in WebHelp.)
• Now let’s say that the first topic in the chapter is About the Terminology Browser. You insert a Filename marker in the topic heading and define the marker as about_terminology_browser.

During import, Flare creates one file for the chapter and a second file for the topic:

• intro_browsing_terminologies.htm
• about_terminology_browser.htm

You can set the permitted length of file names in the Flare import settings.

Adding a custom Filename marker to a FrameMaker file

To add the custom Filename marker to a file, follow these steps:

1. Select the following menu command: Special > Marker. The Marker window opens.
2. Click the Marker Type drop-down list.
3. Click Edit in the bottom of the list. The Edit Custom Marker Type window opens.
4. In the new window, follow these steps:
   1. Type Filename.
   2. Click Add.
   3. Click Done.

Adding the new marker to a FrameMaker chapter
or topic heading

To add the new marker to a chapter or topic heading, follow these steps:

1. Click anywhere on a chapter or topic heading.
2. Select the following menu command: Special > Marker.
3. In the Marker Type list, select Filename.
4. In the Marker Text box, type the file name that you want Flare to use for the current topic. Remember, you don’t need to append the .htm extension.
5. Click New Marker.

I highly recommend this method. It’s very helpful when you need to find content in your new Flare project.

5. Specify Adobe Distiller settings
for optimal image quality.

Since Flare uses Adobe Distiller to convert images, you can use Distiller to improve image quality in the imported FrameMaker content. To accomplish this, you need to specify custom Distiller settings and save them as a custom .joboptions file.

To specify your Distiller settings, follow these steps:

1. Open Adobe Distiller.
2. Click Settings > Edit Adobe PDF Settings.
3. Select the Images folder on the left.
4. For each Downsample setting, select Off.
5. For each Image Quality setting, select Maximum.
6. Click Save As.
7. Name your custom settings file. For example, mine is flareimport.joboptions.
8. Click Save.
9. Click OK to close the settings window.
10. Close Distiller.

Distiller uses the last saved file, so it will use your custom file.

Questions?

The basic steps that I have covered in this post will help you prepare your FrameMaker files for importing into MadCap Flare. I didn’t discuss the time-consuming task of mapping FrameMaker styles to Flare equivalents. I will cover that subject in an upcoming post.

As always, I welcome your questions and comments.

Back to top

Interested in learning more about the Darwin Information Typing Architecture (DITA)? I recommend that all information developers at least break the surface. Regardless of whether you plan to adopt DITA, you can benefit from studying it. You can even borrow from its lean, efficient writing model.

I have been a fan of modular, “chunked” writing since I took an Information Mapping (IM) course years ago. Although I see value in using IM, I prefer DITA’s open, simplified, XML-based model. I appreciate its emphasis on standardization and content reuse. I like the flexibility for using specialized information types. Although none of my clients have adopted DITA, I study it because I have a driven fascination with information architecture and structure.

Toe in the water or swan dive?

Most of the available information about DITA is on the web, but at least three DITA-related books have been released (as far as I know). Each of the following titles is a great resource for neophytes who find the formal specification a bit intimidating but who would like to learn more about—and possibly even experiment with—DITA.

DITA 101: Fundamentals of DITA for Authors and Managers

This 2009 release is written by Ann Rockley, Steve Manning, and Charles Cooper, three esteemed members of the Rockley Group. The book provides a straightforward introduction to DITA without becoming mired in technical details. It provides an overview of the DITA architecture, explains the benefits, and gives advice for planning a DITA implementation. It includes just enough “Advanced Stuff” (the name of the final section) to orient you toward the language of DITA. Best of all, it’s written in the same crystal clear style as Managing Enterprise Content, also a Rockley publication and one of the best books on content management.

DITA 101 is a “toe in the water” book. If you need to make a business case for DITA or compose an elevator speech, this book is your best resource.

Practical DITA

Author Julio J. Vazquez places more emphasis on the planning and execution of DITA projects. In Practical DITA, he encourages authors to start with a visual map of their information set and refer to the map throughout the information development process. He emphasizes the importance of audience and task analysis.

Of the three books discussed here, Practical DITA offers the most detailed writing advice. Vazquez introduces the basic DITA information types and explains the role of each. For example, he lists questions that a concept topic should answer. He recommends that cognitive tasks be written as concepts. He emphasizes the importance of writing “generically” and limiting related links to external content.

Practical DITA also exposes readers to the basic mechanics of DITA. The author covers such specifics as semantic naming and common semantic elements, syntax diagrams and how to create them, filtering and flagging, and linking relationships.

If you are committed to DITA adoption or simply want to develop a test project, I recommend Practical DITA as prerequisite reading. This is your “starting to dog paddle” book.

Introduction to DITA:
A User Guide to the Darwin Information Typing Architecture

Introduced in 2006 by Comtech, this book is a comprehensive tutorial. After a brief overview of the DITA architecture and the core information types, it plunges headlong into hands-on exercises. You open your XML editor and build topic examples. You work with DITA maps. You learn techniques for content reuse and specialization. You install the DITA Open Toolkit and build output.

Introduction to DITA is your “starting to swim” book. This book is the choice for information developers who want experiential guidance in DITA content creation. You not only learn by doing, but you also become acquainted with many DITA elements. Although I recommend this book for practice, I give equal weight to Practical DITA for its sound advice.

Ready to take the plunge?

Good luck on your DITA journey! I have provided links for online DITA resources and for each of the three books discussed here. If you have additional resources or comments to share, please write.

Explore some online resources

• Learn more about DITA from the perspective of its creator, IBM
• Read the OASIS DITA Specification
• Visit the online community for the DITA standard
• Read the Wikipedia entry for DITA

Buy a book

• DITA 101: Fundamentals of DITA for Authors and Managers
• Practical DITA
• Introduction to DITA: A User Guide to the Darwin Information Typing Architecture

Back to top

Though I teach most MadCap Flare classes online these days, I am scheduled to teach a live Flare Single Sourcing class on June 3, 2009, in Arlington, VA.

About the single sourcing class

The single sourcing class is a one-day, hands-on session that uses a scenario-based model to teach you how to single source your content with Flare. The course includes an overview of single sourcing for those who are new to the concept. It also includes advanced tips and best practices for experienced information developers.

In the course scenario, One Source Hotels is expanding to open two resort hotels: one in the US and another in Canada. The company needs to develop policies and procedures for the new hotels. They need to single source one set of content to account for differences between the customs and the legal requirements of the two countries. They need to publish to HTML and PDF.

Course prerequisites

If you are a beginning Flare user and are unfamiliar with the Flare work environment, I recommend that you take the Flare Basic/Intermediate class before attempting the single sourcing class. Unfortunately, we simply cannot cover the work environment in detail. If you have no formal Flare training but are comfortable working with the product, then you will will probably do well in the single sourcing class.

Course highlights

The single sourcing course covers many powerful Flare features, including

• re-using content
• maintaining a linked workflow where contributors are writing in Word and FrameMaker and publishing in Flare
• creating ad hoc tables of content for different outputs
• using Flare page layouts for printed output
• using snippets to reuse content with embedded conditions
• using variables in topics and in a TOC
• running builds from the command line and automating builds with batch files
• creating multiple targets (one online and one print target for each hotel)

sharing content and resources using Global Project Linking.

Details for the upcoming session

• When: Wednesday, June 3, 2009, from 9 am to 5 pm
• Where: 2001 Jefferson Davis Highway, Suite 610,
  Arlington, VA 22202 (Crystal City, accessible by Metro)
• Price: $599 per student
• What to Bring: Laptop with Flare 4.2.1 installed. If you need to use a trial version, MadCap will provide a temporary key.

Questions and registration

Contact Jennifer Morse, Senior Territory Manager, MadCap Software:

• Direct: +1.858.320.0387×212
• Toll Free: 1.888.623.2271×212
• Fax: 858.320.0338
• Email: jmorse@madcapsoftware.com
• Curriculum outline: http://tiny.cc/YcylK

Even if you don’t live in the Washington, DC, area but live within a reasonable travel distance, I hope that you will join us.

I am presenting at an upcoming STC Washington, DC (STC WDC) chapter meeting. I will demonstrate and discuss many of the outstanding single-sourcing features that MadCap Flare offers.

Here are some basic details:
Date: Tuesday, April 21, 2009
Time: 6:30 – 8:30 p.m., US EST
Place: Silver Spring Library

If you are in the Washington, DC, area, I hope to see you there!

Visit the event page and register for the event.