extracting deliverables from dita

Extracting deliverablesfrom DITA

Sarah O'KeefeScriptorium Publishing

Preliminary notes

You should be hearing the presenter's audio at this point.All participants are muted.Use the Questions tab in the GoToWebinar control panel to ask questions anytime during the session.The webcast is being recorded. No participant information appears in the recording.The Q&A period at the end of the event will not be recorded.

Poll: What is your DITA status?

DITA deliverable categories

HTMLPDFCustom output

Flickr: freewine

HTML output options

DITA Open ToolkitVarious help authoring/conversion tools

FlareRoboHelpePublisher ProDITA2GO

DITA Open Toolkit process

Install the DITA Open Toolkit (!)JavaAntXSL processorXSL-FO processor (for PDF)Possibly other bits and pieces

Modify component files to get the output you wantGenerate output from the command line

Help authoring tools

Set up template/configurationImport DITA content(optionally) Make changes in the help authoring toolPublish to HTML

About those last-minute changes…

The traditional authoring/publishing model allows them.The automated publishing model eliminates them.The transition to the “no tweaking” mindset can be painful.What are the costs and benefits?

The DITA Open Toolkit is the best choice for HTML.

Light customization with CSSIn-depth customization with XSLNo arbitrary formattingComplete automation

Flickr: bobistraveling

The special case: WebHelp

WebHelp = HTML-based help system with tripane interface (content, index, search)No support in DITA Open Toolkit (custom build of tripane interface required)Commercial support via XMetaL, Flare, Trisoft, ePublisher Pro, DITA2GO, and perhaps othersBalance DITA Open Toolkit customization effort against license costs

PDF options

DITA Open ToolkitPage layout applicationsOthers

Flickr: freewine

PDF publishing is hard because:

Printed page layouts have more options than HTML layouts.Extensible Stylesheet Language Formatting Objects (XSL-FO) needs to support sophisticated page layout options.Pushing XML into page layout tools is challenging.Automation means giving up page-by-page formatting.

Poll: The five stages of DITA-based PDF publishing

What's your stage?

Please choose one of the following terrifying options:

DITA Open ToolkitPage-based layout tool

FrameMakerInDesignQuark

Help authoring/conversion toolRoboHelpePublisher ProFlare

PDF through the DITA Open Toolkit

Very difficult to configureNo “tweaking” to fix copyfitting problemsAlmost certainly the long-term winner

DITA Open Toolkit process

Customize default PDF output to your requirements (once)Make fonts available to FO processor (once)Run Ant command to generate PDF

DITA Open Toolkit challenges

FontsFormattingFoggy FOFOP foibles

PDF via FrameMaker

Configuration, at a minimum, requires modifying a formatting templateNice PDFCan tweak to adjust pagination

FrameMaker process

Modify the template to meet your requirements (once)Manage white space (tabs, newlines) (once)Open the map file(v8 and earlier) Generate intermediate bookSave as PDF

FrameMaker pitfalls

Sensitive to whitespaceDITA specializationsRound-trippingAuthoring

FrameMaker recommendations

Use DITA-FMx plug-in

PDF via InDesign

Beautiful typographyCan tweak to adjust paginationNo default support for DITAExtensive configuration requiredWhitespace in XML results in anaphylactic shock for InDesign

InDesign process

Transform DITA content into “InDesign-friendly” XML via XSLT (once)

Flatten map filesResolve and flatten content references (conrefs)Modify structure of images and tablesControl whitespaceDo something about xrefs with InDesign scripts

Set up template in InDesign (once)Import modified XML into InDesign

DITA to InDesign challenges

Extensive preprocessingRound-trippingAuthoringWhite space

What about the help authoring tools?

Yes, if you need cross-browser, cross-platform help.Not the best choice for PDF only.

What are your PDF priorities?

For typography, choose InDesign or similar.For automation, choose the DITA Open Toolkit.For a middle ground, choose FrameMaker.

Lower your standards.

Does your audience care about fine typography?Less copyfitting = greater automation

Factors to consider for PDF output

Platform requirementsTechnical resourcesTypography requirementsVelocityVolumeVersioning

Poll: How are you creating (or planning to create) PDF output?

DITA Open Toolkit PDF is not necessarily ugly.

It just starts out that way.Making it pretty is a lot of work.

Custom output examples

Your own implementation of web-based helpMan pages and other custom markupBuilding to an existing formatting specificationCustom markup, such as IDML, XPS, or MIF

Flickr: markdevries

XSL programming skill is an issue

In-house resourcesContractors or consultants?Technical skills required are beyond “typical” FrameMaker templates, HTML coding, and CSS

Flickr: jinxmcc

Automation has advantages

Incremental builds (nightly updates)Zero manual formattingExcellent localization support in DITA Open Toolkit

Automation has disadvantages

Initial configuration effortNo intermediate file for last-ditch copyfitting or content changesNo book-by-book customization

Overall recommendation for HTML

Use the DITA Open ToolkitAutomation is more valuable than ability to finagle

Overall recommendation for PDF

Weigh the benefits of automation against the difficulty of implementing XSL-FORemember that localization support in DITA OT is excellent (and extensive)Consider the value of existing assets (FrameMaker or InDesign templates)How strict are your output requirements? How strict do they need to be?

Questions? Comments?

Contact information

Sarah O'Keefeokeefe@scriptorium.comwww.scriptorium.comPhone: +919 459 5362Twitter: @sarahokeefe