XML 2007—Boston, MA © 2007 Really Strategies, Inc. 1 DITA Quick Start Eliot Kimber XML 2007

XML 2007—Boston, MA

© 2007 Really Strategies, Inc.1

DITA Quick Start

Eliot Kimber

XML 2007



Agenda

What is DITA?

DITA in Action Editing Publishing

Key DITA concepts Topics: Modular information Maps: Dynamic assembly and linking Specialization: Controlled extension Conref: Use by reference Applicability/conditionality



About Me

Senior Solutions Architect at Really Strategies, Inc.

Worked as tech writer at IBM for 10 years

Been Using generalized markup for 20+ years

Member of DITA Technical Committee Founding member of XML Working

Group Co-editor of HyTime Standard (ISO/IEC

10744:1996)



What Is DITA?

The Standard and Its Intended Use



Darwin Information Typing Architecture

XML application for modular documents OASIS Standard, currently at version 1.1 Donated to OASIS by IBM in 2004 Originally designed to meet IBM's

requirements for technical documentation authoring and publishing

Optimized for, but not limited to, technical documentation

Already widely adopted within computer hardware and software industry



Key Requirements DITA Meets

Makes large-scale re-use of content practical and manageable

Enables blind interchange of content without requiring a single,invariant, DTD

Makes sophisticated linking practical and manageable without complex management tools

Makes Web-based delivery as easy as possible



Key DITA Features Modular content: “topic-based authoring”

Content organized into small, inherently-reusable modules called “topics”

Topics organized for publication and delivery using “maps” Clearly distinct information types: concept, task, and

reference

Maps: Link-based assembly of topics to create publications

Specialization: New element types formally based on core DITA types

Applicability/conditionality at the element level

Conref: Link-based use-by-reference of arbitrary content



Compare with: DocBook

DocBook is an OASIS XML standard for technical documentation

DocBook focuses on generality and unconstrained and informal extension

DocBook optimized for: Ease of authoring of books as books Ease of legacy conversion

No feature comparable to DITA maps

Enables use of XInclude for re-use



Compare With: S1000D

S1000D has similar modularity and re-use goals

S1000D more focused on manufacturing industry requirements

Lacks DITA's controlled extension mechanism (specialization)

Use mandated by certain industries and government bodies

Ongoing work to harmonize/align S1000D and DITA



DITA Open Toolkit

General-purpose, cross-platform, open-source processor for DITA content

Maintained by IBM and DITA community through SourceForge

Provides plug-in architecture for adding functionality

Out-of-the-box produces: HTML PDF Eclipse help RTF



Product Support

Many products have built-in or optional DITA support

All major XML editors: Arbortext Editor Xmetal Syntext Serna OxygenXML XMLMind FrameMaker In.Vision



Product Support (cont.)

Most XML-Aware CMS systems: IXIASOFT DITA CMS Framework Xhive Docato Really Strategies RSuite CMS XyEnterprise Contenta Astoria On-Demand SiberLogic SiberSafe DITA Edition Vasont DocZone.com More all the time—see

http://www.ditanews.com/tools/dita_xml_cms/



Large and Active User Community DITA User's Mailing List:

[email protected] Several DITA-specific Web sites:

http://dita.xml.org/ http://www.ditablog.com http://www.ditanews.com/ www.oasis-open.org

DITA User Groups in many cities: Boston, Austin, Denver, Indianapolis, Silicon

Valley... Toronto, Vancouver, UK...

mailto:[email protected]

http://dita.xml.org/

http://www.ditanews.com/



Summary

DITA is an XML application for authoring and delivering sophisticated modular documentation with focus on re-use and linking

Relatively young standard but based on solid, proven foundation

Large and growing support infrastructure

Quickly becoming preferred approach for technical documentation authoring and management



Takeaway: DITA Lowers Cost of Entry DITA lowers to almost zero the cost of

entry to the use of very sophisticated XML techniques: DITA can be used for authoring out-of-the-

box Open Toolkit provides sophisticated

processing for free: HTML, PDF, more Even inexpensive XML editors offer solid

features: XMLMind, OxygenXML, Syntext Serna

XML CMS not required for small and medium scales

Can get started quickly at low cost



Implications for Evaluators

Low cost of entry means you can: Can get started without a lot of up-front

analysis Try it out with minimal investment Show tangible results (published HTML or

PDF) quickly Experiment with different approaches easily

Specialization means you can add support for local requirements iteratively Start small and build as needed Implementation cost is incremental



DITA In Action

Show me something concrete please...



Scenario: Travel Guide

Have existing travel guide, want to use DITA for authoring and production

Travel Guides: Are inherently modular Reasonably consistent across titles Combine concept, task, and reference info Need applicability: locale, audience,

publication type Need ability to create new packages quickly

Ideal candidate for use of DITA



Topic Content

Each region (country, region, state, city, neighborhood) has conceptual introductory content: authored as concept topics

Attractions authored as reference entries: Lodging Eating Entertainment Etc.

Guided tours are tasks



Real Data: Topics

Let's see some topics in an Editor: Region introduction concept Attraction reference entry Guided tour task



Publication Structure: Maps

Specific publications defined using DITA maps

Organizes the topics into an appropriate sequence and hierarchy

May is only headings and links, no content

Includes topic-to-topic links that are map (context) specific



Real Data: Maps

Let's see a publication map: Guide to Guangzhou, China Organized by neighborhood Links city-specific topics to general topics re-

used across publications:Chinese language tipsMenu reader



Real Data: Publish the Guide

Using DITA Open Toolkit: Publish to HTML Publish to generic PDF

Using custom software: Publish print publication using Typefi and

InDesign



DITA To the Rescue: Add Nature Guide Info

Scenario: Want to produce new guide that includes

nature guide content (“Birds of China”) Have purchased nature guide content in

DITA Need to quickly integrate with existing guide

and republish Boss: “I need it yesterday!”

Go...



Real Data: Nature Guide Data

Show nature guide topics in an editor...



Real Data: New Publication

Copy existing publication map

Change the title

Add references to nature guide topics

Publish new guide

Show HTML and print results

Boss: “Good job, take the rest of the day off!” (as if).



Key DITA Concepts

Where we learn about the fiddly bits...



General DITA Markup Design

Looks a lot like HTML, mostly



Borrows HTML Names Where it Can

Intent is to be as familiar as possible

Borrows HTML names where appropriate, e.g.: <p> <ul>, <ol>, <dl>, <i>, <b>, etc.

Uses CALS/OASIS table model for tables

No generic nested division, only “section”, which cannot nest

Topics and maps used to create deep hierarchies.



Generic Types are Very General

DITA doctypes are usuable out of the box

But, like DocBook, are very general and fairly wide in scope

Most users will configure their local “shell” doctypes to expose only what they need

In DITA 1.2 will have more configuration control of content model details

Expect to do some configuration even if you don't plan to specialize



DITA Topics

“Single idea, thing, or task”



Topics: Bite-Sized Info Chunks

Conceptually: A single, stand-alone, idea (concept), thing

description (reference entry), or task (atomic set of steps in a process)

Smallest unit of general re-use and interchange

In practice: Some topics may be very small due to DITA

markup design details A single “logical” topic may consist of a main

topic with nested subtopics



Generic Topic: <topic>

Generic topic is base for all more specialized topic types

Basic model is: Required title Optional prolog (for metadata) Optional topic body Optional nested topics

Topic body contains all the usual stuff: Paragraphs, tables, lists, figures, etc.



Topic Types: Task, Concept, Ref

DITA codifies three distinct information types: Task: sequence of steps to achieve a specific

result Reference: Factual description of a thing

(part, command, code object, abstract thing, etc.)

Concept: Conceptual information that supports understanding

At XML level, three topic types have different content models

All are specializations of generic “topic”



Task Topics

Intended to describe a single atomic set of steps

Steps may have one level of substeps

Complex processes represented using multiple task topics organized together using maps

Task markup in 1.1 may be too limiting for some users

DITA 1.2 will provide more generic task markup



Sample Task Topic

<task id=”mytask”> <title>Buy a Bus Card</title> <taskbody> <steps> <step> <cmd>Go to any convenience store or train station</cmd> </step> <step> <cmd>Ask for a “bus card”</cmd> </step> </steps> </taskbody></task>



Reference Topics

Intended to describe a thing

Should minimize conceptual content

Typical uses: Messages and codes Part descriptions Program objects, APIs, etc. Command reference (e.g., “man pages”)

Use generic “section” element to define consistent subdivisions

Often first target for specialization



Sample Reference Topic

<reference id=”white-swan-hotel”> <title>White Swan Hotel</title> <prolog> <data name=”cost”>high</data> <data name=”stars”>5</data> </prolog> <refbody> <section spectitle=”Description”> <p>Known as the hotel used by adoptive parents...</p> </section> <section spectitle=”Location”/> <p>On Shamian Island at ... </p> </section> <section spectitle=”Ammenities”> <simpletable> <tbody>...</tbody> </simpletable> </section> </refbody></reference>



Concept Topics

Place for what and why information

In essence: if it's not task or reference, it must be concept

Can use nested concept topics to express a traditional book hierarchy

Should not use <section> in concept topics unless you're defining a repeating structural pattern



Sample Concept Topic

<concept id=”conceptid”>  <title>Welcome to Guangzhou</title> <conbody> <p>The Pear River Delta is among China's most polluted regions, and that is saying a lot. From the southern suburbs of Guangzhou city to the northern edge of Shenzhen, industry stretches in all directions. So why visit? The answers are myriad. History enthusiasts head to Guangzhou, Guangdong province's ancient capital and the historic center of both Cantonese culture and the revolution that overthrew the last dynasty.</p> <p>Gourmands flock to both Guangzhou and Shenzhen to indulge in some of the best examples of Chinese cuisine—and increasingly, the world—at all price ranges. Culture vultures don't mind putting up with the pollution and chaos for a chance to visit the many temples, shrines, and museums scattered throughout the region. And shop-a-holics?</p> </conbody></concept>

http://www.fodors.com/world/asia/china/guangzhou%20&%3B%20shenzhen/



Your Own Topic Types

Specialize from one of concept, task, or reference

Or specialize from topic if the three base types don't make sense

Start by using base types and specialize when you see consistent patterns of use emerge.

Most users find it valuable to specialize reference topics to reflect the unique nature of the things they're documenting



DITA Maps

Link-based assemblies of topics



Maps Pull It Together

Topics are standalone, need to be placed into a context to have full meaning

Maps apply structure to topics: Define organizing hierarchies Define sequences of topics Define topic-to-topic links in the context of

the maps

Maps define view contexts over sets of topics



Map Content

Top-level “map” element

Optional map title (DITA 1.1)

Optional map-level prolog

Zero or more topic reference elements (topicrefs may nest)

Zero or more relationship tables

Maps do not contain topics directly, only by links

Maps may link to submaps



Four Forms of Topic Reference Topic ref:

Points to a topic Optionally, assigns a map-specific navigation title or

metadata

Topic head: Defines a navigation title but does not reference a topic. Creates a layer of hierarchy in the map structure

Topic group: No title or topic reference. Used to group topic references together for convenience or

to establish an order relationship

Map reference: points to a sub map Indicated by format="ditamap" on topicref element



Sample Map

<map> <title>Guangzhou City Guide</title> <topichead navtitle=”Orientation”> <topicref href=”topics/getting-there.xml”/> <topicref href=”topics/language-and-culture.xml”/> </topichead> <topichead navtitle=”Featured Attractions”> </topichead> <topichead navtitle=”Shamain Island”> </topichead> <topichead navtitle=”Listings”> <topichead navtitle=”Lodging”> ... <topicref href=”white-swan-hotel.xml”/> ... </topichead> <topichead navtitle=”Dining”> ... <topicref href=”lucys-shamain-island.xml”/> ... </topichead> </topichead></map>



Relationship Tables (<reltable>)

Create topic-to-topic links within a map

Defined using tables: Each row is one link Each cell in a row is one end of the link

Functionally equivalent to XLink extended links

Allows same topic to link to different topics in different maps



Sample Map With A Reltable

<map> <title>Guangzhou City Guide</title> <topichead navtitle=”Orientation”> <topicref href=”common/getting-there.xml”/> <topicref href=”common/language-and-culture.xml”/> </topichead> ...<reltable> <relrow> <relcell> <topicref> <topicref href="lodging/white-swan-hotel.xml"/> </topicref> </relcell> <relcell> <topicref href="tours/walking-tour-01.xml"/> </relcell> </relrow> </reltable></map>



Relationship Table Processing

Default Toolkit processing is to generate “related links” in the rendered topics

Custom processes could do other stuff: Different way of showing the links Pull link targets as sidebars Generate multi-frame views Etc.



DITA Specialization

Controlled extension of document types from the base DITA types



DITA is an Architecture

DITA defines an architecture for creating new document types Documents with these types are still DITA

documents but Will have unique content models May have unique element types May have associated custom processing



Business Value of Specialization

Lets you have markup specific to your business requirements

Without compromising the ability to interchange your data with other DITA users and systems

All DITA-aware tools should “just work” with all valid specialized DITA documents

Adding custom functionality should be an incremental cost, not a re-implementation cost



Specialization Modules

“specialization module”: A set of element type declarations designed to be used as a unit

Two types of modules Structural modules define new map or topic

types Domain modules define elements for use

within maps or topics that are specific to a particular subject domain. E.g.:

Programming domainTravel domain



Combining Modules

Modules are combined together to create a working document type

One or more structural modules plus one or more domain modules

Concrete document type is referred to as a “shell” (e.g., “shell DTD”).

The shell declares which modules it uses

Can compare two documents to see if they use “compatible” modules



Specialization vs Configuration

“Configuration” is process of combining existing modules to create a new shell document type

“Specialization” is process of creating new modules

Can do configuration without specialization

Configuration required to use newly-created modules



You Should Always Use Local Shells

Even if you don't plan to specialize, you should use local shells

Lets you turn off things you don't need (e.g., programming and UI domains when creating travel guides)

Prepares you for inevitable day when you will want to add a new module (your own or someone else's)

Eat minor configuration pain up front, then you don't have to worry about it later



How Specialization Works: The class= Attribute

Every DITA element type has an associated module and class name: Class="- topic/topic " Class="- topic/body " Class="- topic/p "

Specialized elements are based on base classes: Class="- topic/topic concept/concept "

Class="- topic/body concept/conbody "



Constraints on Specializations

All specialized elements must be based on an existing typed defined in DITA standard

Specialized element must be as or more constrained then base type Optional things can be omitted in

specialization Required things must be represented in

specialization

Cannot add arbitrary attributes



Attribute Specialization

Can specialize from one of two attributes: base= and props=

Specialized attributes are global (must be allowed on all element types)

Base= attribute has no specific meaning

Props= attribute is for applicability/conditionality



Takeaway: Specialization Is Easy Creating specialization modules is

largely mechanical: see my specialization tutorial

Hard part is working out your requirements

DITA makes it easy to experiment and refine iteratively

Because specialized documents get default processing, can experiment with new structures without need for new processing code



Applicability/Conditionality

Bind elements to specific conditions to which they apply



DITA Concept: Properties Attribute

Associates an element with one or more classifying property values

Can have any number of types of property: Audience Product type Platform Locale Etc.

DITA defines a start set of “props” attributes

Can specialize props= to define your own



Props Attribute Processing

Default is to include/suppress content based on active properties In DITA OT, controlled via ditaval file

Can also use for labeling (effectivity)

Or simply treat as descriptive metadata



Sample Props Usage

Specialized topic that declares the attribute “locale=” as a specialization of “props=”:

<?xml version=”1.0”?><!DOCTYPE guide-concept SYSTEM “guide-concept.dtd”><guide-concept id=”changing-money”> <title>Changing Money in China</title> <gc-body> <p locale=”uk”>At time of writing the British Pound was worth approximately 10.5 Chinese Yuan.</p> <p locale=”us”>At time of writing the US Dollar was fixed to an exchange rate of 4.85 Chinse Yuan.</p> </gc-body></guide-concept>



Content Use by Reference

Link-based re-use of individual elements



“conref” Facility

Any element can use conref= attribute to point to a replacement element

Target element must be same element type

Any content of referencing element is ignored for processing

Source and target attributes are merged

Creates topic-to-topic dependencies

Avoid if possible: try to re-use at topic level



Sample Content Reference Document “note-library.xml”:

<topic id=”re-usable-notes”> <title>Reusable Notes</title> <body> ... <note id=”electrical-danger” type=”danger”> <p>High voltage and strong current. Beware!</p> </note> ... </body></concept>

Document “task-0001.xml”:

<task id=”task-0001”> <title>Replace Capacitor</title> <taskbody> <context> <note conref=”note-library.xml#re-usable-notes/electrical-danger”/> ....



Summary

DITA is a sophisticated XML application for structured content

Lowers cost of entry to sophisticated use of XML to almost zero

Optimized for modularity, re-use, and interchange

Key feature: independent topics dynamically organized using maps

Specialization compromises interchange with flexibility



Resources

OASIS Open: www.oasis-open.org

DITA Open Toolkit: http://dita-ot.sourceforge.net

DITA Users on Yahoo Groups

DITA FrameMaker users: [email protected]

http://dita.xml.org

DITA blog: www.ditablog.com

Eliot's specialization tutorial:www.xiruss.org/tutorials

http://www.oasis-open.org/

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

mailto:[email protected]

http://dita.xml.org/

http://www.ditablog.com/

http://www.xiruss.org/tutorials

70