XML 2007—Boston, MA
© 2007 Really Strategies, Inc.2
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.3
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)
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.5
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.6
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.7
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.8
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.9
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.10
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.11
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.12
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/
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.13
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...
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.14
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.15
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.16
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.17
DITA In Action
Show me something concrete please...
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.18
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.19
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.20
Real Data: Topics
Let's see some topics in an Editor: Region introduction concept Attraction reference entry Guided tour task
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.21
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.22
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.23
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.24
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...
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.25
Real Data: Nature Guide Data
Show nature guide topics in an editor...
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.26
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).
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.27
Key DITA Concepts
Where we learn about the fiddly bits...
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.28
General DITA Markup Design
Looks a lot like HTML, mostly
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.29
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.
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.30
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.32
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.33
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.
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.34
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”
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.35
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.36
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>
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.37
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.38
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>
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.39
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.40
Sample Concept Topic
<concept id=”conceptid”> <!-- Content from http://www.fodors.com/world/asia/china/guangzhou%20&%3B%20shenzhen/ --> <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>
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.41
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.43
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.44
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.45
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.46
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>
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.47
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.48
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>
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.49
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.
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.50
DITA Specialization
Controlled extension of document types from the base DITA types
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.51
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.52
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.53
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.54
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.55
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.56
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.57
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 "
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.58
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.59
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.60
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.61
Applicability/Conditionality
Bind elements to specific conditions to which they apply
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.62
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.63
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.64
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>
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.65
Content Use by Reference
Link-based re-use of individual elements
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.66
“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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.67
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”/> ....
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.68
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
XML 2007—Boston, MA
© 2007 Really Strategies, Inc.69
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
Top Related