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.

This is the sixth and final installment in a series of articles outlining my suggestions for developing a Flare 4 print publishing strategy. Each article represents a stage in the process. This article provides suggestions, tips, and key points for successful print publishing with Flare. It is not a replacement for Flare’s comprehensive online help and how-to guides.

Recommended prerequisite reading:

• Stage 1: Laying the Foundation
• Stage 2: Defining Styles
• Stage 3: Creating a Book Structure
• Stage 4: Designing a Book Layout
• Stage 5: Assembling a Book

Here’s where all of your hard work in setting up a Flare print publishing infrastructure pays off. All you have to do is configure a target for printed output, generate the build, and then publish the deliverable.

If you require more than one print target, add as many as you need (Project > Add Target). For example, if you need to publish to both Word and PDF, you can create a target for each.

Goal of this stage: Configure, build, and publish.

Step 1: Configure the target file.

The following tables list target settings that are specific to printed output.

Basic tab settings

Conditional Text tab settings

Variables tab settings

Advanced tab settings

Printed Output tab settings

Step 2: Build the target.

Once you have selected all of the desired settings, save and build the target. Examine the output and make any necessary adjustments.

Step 3: Publish the target.

Just as you publish online output to make it available for your users, you also need to publish your printed documents and books. For more information about publishing, see my article covering Flare publishing destinations.

Conclusion

Wow, the epic is finished! To my Flare students who asked for this information months ago, I hope it was worth the wait. I have juggled the writing with a busy schedule and other responsibilities, so publishing these articles took longer than I had anticipated. I hope that you find the information helpful.

Please visit this site often for more frequent Flare tips.

Back to top

This is the fifth installment in a series of articles outlining my suggestions for developing a Flare 4 print publishing strategy. Each article represents a stage in the process. This article provides suggestions, tips, and key points for successful print publishing with Flare. It is not a replacement for Flare’s comprehensive online help and how-to guides.

Recommended prerequisite reading:

• Stage 1: Laying the Foundation
• Stage 2: Defining Styles
• Stage 3: Creating a Book Structure
• Stage 4: Designing a Book Layout

Once you have set up a book structure and designed the book layout, you’re ready to assemble the book. Don’t confuse this with generating a book. You’ll do that in the final stage by setting up and building a print target.

Goal of this stage: To assemble a book using a print-only table of contents to specify the book sections.

Step 1: Create a print-only TOC.

When you create a new Flare project, Flare includes one Master TOC (.fltoc) file. You are not restricted to using only the Master file. In fact, you can add as many TOCs as you need and use them for various targets. You can also designate any TOC as the Master TOC by right-clicking its name and selecting Make Master TOC from the shortcut menu.

For this stage of the print publishing process, you need to add a print-only TOC to your project. You will use the new TOC to assemble the sections of your printed book. The following procedures explain two different ways to add the TOC.

Adding a TOC using the Project menu

To add a TOC using the Project menu, follow these steps:

1. Select the following menu command:
   Project > Add Table of Contents
2. In the Add TOC window, do one of the following:
   • Click the button to the right of the Source File field and browse for a saved TOC template; or
   • Type a file name that expresses the intent of the new TOC (for example, PrintOnly).
3. Click Add.
4. Click OK to confirm that you want to copy the file to the project. Flare adds the new TOC to the TOCs folder in the Project Organizer.

(Alternate) Adding a TOC by copying another TOC file

If you want to re-use content from an existing TOC, copy it and use its hierarchy as a starting point for your print TOC. To copy an existing TOC file, follow these steps:

1. Right-click the existing TOC, then select Copy from the shortcut menu.
2. Right-click anywhere in the Project Organizer pane, then select Paste from the shortcut menu. Flare adds the new TOC to the TOCs folder in the Project Organizer. The new TOC is named Copy of <original file name> (for example, Copy of Master).
3. Rename the new file using a name that expresses the intent of the new TOC (for example, PrintOnly).

Step 2: Assemble the hierarchy for the new book.

If you cloned the Master TOC, you may want to add or remove specific books and topics. Regardless, add TOC entries for the print-only topics that you created in Stage 3 of the print publishing process. For example, if you created topics for a cover page, TOC section, lists of figures and tables, glossary, and index, add TOC pages for those topics and link the pages to the topics.

A simple way to simultaneously add TOC pages and link them to topics is to drag the topics into the TOC from the Content Explorer. To do this, follow these steps:

1. Open the print-only TOC.
2. Display the Content Explorer.
3. Locate your print-only topics. I recommend storing all of them in the same subfolder.
4. Drag each topic to a specific location in the TOC. This step creates a TOC page and links it to the topic.
5. Save the TOC file.

The following image shows an example of a completed print-only TOC hierarchy. The standalone pages in the TOC are linked to print-only topics, and the books are linked to content topics.

Step 3: Map TOC pages to book sections.

The standalone pages that you created in Step 2 now represent book sections. You can specify the layout for each section by mapping the TOC page properties to specific page layouts.

To map TOC pages to book sections, follow these steps:

1. Open the print-only TOC.
2. Do either of the following to access the Properties window for a TOC page:
   • Double-click the TOC page;
     or
   • Right-click the TOC page, then select Properties from the shortcut menu.
3. Complete the following tasks.

Setting Chapter Break properties

In the Properties window, follow these steps:

1. Click the Printed Output tab.
2. Check the box labeled Start a new chapter document.
   This step enables the rest of the options in the Chapter Break section.
3. Under Configure chapter using this Page Layout, select a page layout. For example, if you have a page layout called Front that includes a cover page and copyright page, you might select Front.
4. Select a Page Type from the drop-down list. The available types come from the page layout that you selected in the previous step. For example, if the Front page layout is set up for a double-sided book, you would most likely select the First page type to start a new section.
5. If you want new chapters to automatically start on right (odd) pages, set the Auto-end on ‘left’ page property to Enabled. 
6. Leave Chapter File Name set to default if you plan to use one file for the printed book. If you plan to use multiple files for the chapters, you can use a target setting to break chapters into multiple files and specify names for each file. For more information, see the help topic titled Specifying Chapter Breaks and Page Layouts.

Setting Page Number properties

To establish a page number format for the current section, follow these steps:

1. Ensure that the Printed Output tab is still visible.
2. In the Page Number section, select settings according to what you want to do:
   1. To start page numbering at a specific number, enter the starting number in the box.
   2. To control the page number format for the current section, select a format from the Format drop-down list.
   3. To continue page numbering and retain the number format from the previous section, select the Continue from previous option.
3. Click OK to close the Properties window.

Specifying Section, Chapter, or Volume Numbering

The Properties window for a TOC item includes settings for section, chapter, and volume numbers. For example, even if you have set up an auto-numbered style for appendices (such as Appendix {chapnum}), you use TOC settings to ensure that uppercase alpha headings (such as Appendix A) show in printed output.

To specify section, chapter, or volume numbering, follow these steps:

1. In the Properties window, click the Auto-numbers tab.
2. Specify settings as needed in the Section, Chapter, and Volume areas of the tab:
   1. To start numbering at a specific number, enter the starting number in the box.
   2. To control the number format for the current section, select a format from the Format drop-down list.
   3. To start at the same number as the previous section, select Same as previous.
   4. To number consecutively from the previous section, select Continue from previous.
3. Click OK to close the Properties window.

What’s next?

You have completed all of the most time-intensive stages of the Flare print publishing process. There’s only one more thing to do: configure and build your print target.

Back to top