DITA Everydayby Tom Rathkamp

thomas_rathkamp@yahoo.com

Agenda• What is DITA?

• Why DITA? Why NOT DITA?

• DITA Basic Structure

• Topics and Maps

• DITA Transformations (output)

• DITA-Enabled Tools Summary

• Raw DITA vs. DITA-enabled tools

• Re-use basics – the mantra of DITA

• DEMO

• Postlude: Transitioning to DITA

• Questions?

What is DITA?

• DITA (Darwin Information Typing Architecture) is a topic-based XML framework used to support the authoring, management, and publication of technical documentation.

• Contains a core set of information types: concept, task, reference.

• Content is separate from format• DITA consists of two main files: topics and maps

Why DITA?

• Align with software development processes

• Reduces the cost of maintaining and updating information• Reuses information quickly and efficiently across multiple

deliverables• Technology is open, not proprietary and inaccessible. • Why I decided to make to take the plunge.

Why NOT DITA?

• Authoring and technical learning curve

• Minimal deliverables for non-diverse audiences

• DITA-enabled tools are constantly catching up

• Legacy content – time permitting

DITA Basic StructureTopics

(concept, task, reference)

Elements(body, step, note,

etc.)

Attributes(audience, chunk,

product, etc.)

Elements represent types of content that commonly occur in technical documentation. There are “container” elements and “content” elements.

Topics represent general types of information that commonly occur in technical documentation.

Attributes are used to alter the behavior or condition of topic content, depending on the situation or need.

Topics and Maps

• Topics house specific content of a distinct type.• Maps collect topics to achieve deliverables.• <concept> - answers the question “what is”? Provides

summary or background information.• <task> - essential building block for providing procedural

information.• <reference> - layout highly structured data for quick

reference, such as a command reference .• Other non-core topics include machinery, glossary and so on.• Topic files contain .dita file extension.• Map files contain .ditamap file extension.

DITA Transformations (output)

• PDF

• XHTML

• HTML Help

• Web Help

• Eclipse Help

• Java Help

DITA-Enabled Tools Summary

• Adobe FrameMaker (plus DITA-FMx plugin)• Oxygen XML Author• Madcap Flare• Arbortext Editor• Others• Supporting CMS’s – Xdocs, SiberSafe, Iixia, Componize

The challenge with overlap – discussionMy recommendations

Raw DITA vs. DITA-enabled tools

• Get a DITA-enabled tool !!• Learn raw DITA first, even if using a DITA-enabled tool.• For DITA-enabled tool, locate embedded DITA-OT.

Reuse basics – the mantra of DITA

• Author once, use many times• Topic reuse (within same or different map)• Content reuse (conref )

DEMO

Demo Agenda

• Download and set up the DITA Open Toolkit• Review and edit DITA build files• Generate output from the command line• Create topics• Create maps• Generate output with DITA-enabled tool (Oxygen)• Conditional processing• Content reference (conref)• Relationship tables• Simple customization• Toggling between WYSIWIG and Code view

Download and set up the DITA Open Toolkit

• http://dita-ot.sourceforge.net/• Recommended: DITA-OT1.6.1_full_easy_install_bin• Extract contents of ZIP file• Download and install Apache ANT and FOP, Java Development

Kit, and Saxon XSLT processor, and JavaHelp .• Set up environment variables• DITA specification

Review and edit DITA build files

• About Ant - Apache Ant is a Java library and command-line tool whose mission is to drive processes described in build files as targets and extension points dependent upon each other.

• Build files set parameters, determine files to transform, and output folder location.

• Use startcmd.bat file to set environment.

Create topics

• <concept>, <task>, and <reference>• Main elements• Container elements vs. content elements

Create maps

• DITA map vs. bookmap• Topic references• Processing attributes (ex. print and toc)• collection-type attribute• linking attribute

Generate output with DITA-enabled tool (Oxygen)

• Generate PDF and CHM from same map file• Make copy of shipped transformation type (Oxygen)

Conditional processing

• Ditaval file basics• Conditionalize topics in Map file• Uses attributes

Content references (conref)

• Chunks of repeated content for multiple topic• Reused content must work in the new context• New context must reference filename and ID attribute of

reused content• conref=“file.dita#resusedcontent/elementID“• Conref overkill

Relationship tables

• Related topics in Help system• Easier to track cross linking• Main benefit - links don’t live in topic files

Simple customization

• Don’t modify shipped DITA files• custom.xsl• DITA plugins

Toggling between WYSIWIG and Code view

• DITA everyday workflow• All about comfortability and familiarity

Postlude: Transitioning to DITA

• Four components of transition:- Management- Writers- Tools- Content

• Start with small pilot project• Isolate the project from your real work.• Perform a content audit. • Develop a strategy for converting unstructured legacy

content.

Questions?thomas_rathkamp@yahoo.com

Sources• Online

http://dita-ot.sourceforge.net/

http://tech.dir.groups.yahoo.com/group/dita-users/?v=1&t=directory&ch=web&pub=groups&sec=dir&slk=1

http://www.ibm.com/developerworks/xml/library/x-dita1/

http://ant.apache.org/

http://www.xiruss.org/tutorials/dita-specialization/

https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita

• Books

Introduction to DITA – A User Guide to the Darwin Information Typing Architectureby Jennifer Linton and Kylene Bruski

DITA for Practitioners by Eliot Kimber

Several books on XML and XSL