DITA Everyday by Tom Rathkamp

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 Structure 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. - answers the question “what is”? Provides summary or background information. - essential building block for providing procedural information. - 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 – discussion My 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 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,, and 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?

Sources Online users/?v=1&t=directory&ch=web&pub=groups&sec=dir&slk= users/?v=1&t=directory&ch=web&pub=groups&sec=dir&slk= Books Introduction to DITA – A User Guide to the Darwin Information Typing Architecture by Jennifer Linton and Kylene Bruski DITA for Practitioners by Eliot Kimber Several books on XML and XSL