DITA Quick Start Eliot Kimber XML 2007Boston MA

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. 2

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 Hy. Time Standard (ISO/IEC 10744: 1996) XML 2007—Boston, MA © 2007 Really Strategies, Inc. 3

What Is DITA? The Standard and Its Intended Use XML 2007—Boston, MA © 2007

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. 5

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. 6

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. 7

Compare with: Doc. Book is an OASIS XML standard for technical documentation Doc. Book focuses on generality and unconstrained and informal extension Doc. Book 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. 8

Compare With: S 1000 D has similar modularity and reuse goals S 1000 D 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 S 1000 D and DITA XML 2007—Boston, MA © 2007 Really Strategies, Inc. 9

DITA Open Toolkit General-purpose, cross-platform, opensource processor for DITA content Maintained by IBM and DITA community through Source. Forge 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. 10

Product Support Many products have built-in or optional DITA support All major XML editors: Arbortext Editor Xmetal Syntext Serna Oxygen. XMLMind Frame. Maker In. Vision XML 2007—Boston, MA © 2007 Really Strategies, Inc. 11

Product Support (cont. ) Most XML-Aware CMS systems: IXIASOFT DITA CMS Framework Xhive Docato Really Strategies RSuite CMS Xy. Enterprise Contenta Astoria On-Demand Siber. Logic Siber. Safe DITA Edition Vasont Doc. Zone. com More all the time—see http: //www. ditanews. com/tools/dita_xml_cms/ XML 2007—Boston, MA © 2007 Really Strategies, Inc. 12

Large and Active User Community DITA User's Mailing List: ditausers@yahoogroups. com 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. 13

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. 14

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-thebox Open Toolkit provides sophisticated processing for free: HTML, PDF, more Even inexpensive XML editors offer solid features: XMLMind, Oxygen. XML, Syntext Serna XML CMS not required for small and medium scales Can get XML 2007—Boston, MA © 2007 Really Strategies, Inc. started quickly at low cost 15

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. 16

DITA In Action Show me something concrete please. . . XML 2007—Boston, MA ©

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. 18

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. 19

Real Data: Topics Let's see some topics in an Editor: Region introduction concept Attraction

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. 21

Real Data: Maps Let's see a publication map: Guide to Guangzhou, China Organized by neighborhood Links city-specific topics to general topics reused across publications: Chinese language tips Menu reader XML 2007—Boston, MA © 2007 Really Strategies, Inc. 22

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 In. Design XML 2007—Boston, MA © 2007 Really Strategies, Inc. 23

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. 24

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). XML 2007—Boston, MA © 2007 Really Strategies, Inc. 26

Key DITA Concepts Where we learn about the fiddly bits. . . XML 2007—Boston,

General DITA Markup Design Looks a lot like HTML, mostly XML 2007—Boston, MA ©

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. 29

Generic Types are Very General DITA doctypes are usuable out of the box But, like Doc. Book, 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. 30

DITA Topics “Single idea, thing, or task” XML 2007—Boston, MA © 2007 Really Strategies,

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. 32

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. 33

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. 34

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. 35

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> <cmd>Ask for a “bus card”</cmd> </steps> </taskbody> 36 </task> XML 2007—Boston, MA © 2007 Really Strategies, Inc.

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. 37

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. 38

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. 39

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-aholics? </p> </conbody> </concept> XML 2007—Boston, MA 40 © 2007 Really Strategies, Inc.

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. 41

DITA Maps Link-based assemblies of topics XML 2007—Boston, MA © 2007 Really Strategies, Inc.

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. 43

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. 44

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. 45

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> XML 2007—Boston, MA </map> 46 © 2007 Really Strategies, Inc.

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. 47

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 href="lodging/white-swan-hotel. xml"/> </topicref> </relcell> <topicref href="tours/walking-tour-01. xml"/> </relcell> </relrow> </reltable> </map> XML 2007—Boston, MA © 2007 Really Strategies, Inc. 48

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. 49

DITA Specialization Controlled extension of document types from the base DITA types XML 2007—Boston,

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. 51

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 reimplementation cost XML 2007—Boston, MA © 2007 Really Strategies, Inc. 52

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 domain Travel domain XML 2007—Boston, MA © 2007 Really Strategies, Inc. 53

Combining 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. 54

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 newlycreated modules XML 2007—Boston, MA © 2007 Really Strategies, Inc. 55

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. 56

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. 57

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. 58

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. 59

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. 60

Applicability/Conditionality Bind elements to specific conditions to which they apply XML 2007—Boston, MA ©

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. 62

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. 63

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. 64

Content Use by Reference Link-based re-use of individual elements XML 2007—Boston, MA © 2007

“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. 66

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-usablenotes/electrical-danger”/>. . XML 2007—Boston, MA © 2007 Really Strategies, Inc. 67

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. 68

Resources OASIS Open: www. oasis-open. org DITA Open Toolkit: http: //dita-ot. sourceforge. net DITA Users on Yahoo Groups DITA Frame. Maker users: framemakerdita@yahoogroups. com http: //dita. xml. org DITA blog: www. ditablog. com Eliot's specialization tutorial: www. xiruss. org/tutorials XML 2007—Boston, MA © 2007 Really Strategies, Inc. 69

70