DITA Quick Start

DITA Quick StartSelvakumar T.S

August 9, 2009 Cadence Confidential: Cadence Internal Use Only1

Agenda

• A quick look at XML• Understand DITA’s overall approach• Understand DITA’s core content structures and how you

can customize themU d t d th f i DITA• Understand the scope for reuse in DITA

• See DITA at work!!


A Quick Look at XML


The difference between HTML and XML• HTML defines how content is formatted in a web browser; XML defines

what the content is.

• HTML provides a set of predefined tags; XML provides a syntax that allows p p g ; p yusers to define their own tags.

XML is like a

HTML Example XML Example<ul>

<li>Joseph Clark</li> <family>

<father><name>Joseph Clark</name></father>

database!!

p<li>Mary Clark </li><li>Jennifer Clark</li> <li>Joseph Clark II</li>

<mother><name>Mary Clark</name></mother> <offspring>

<child><name>Jennifer Clark</name></child> Josep C a /<li>Taylor Clark</li>

</ul>

<child><name>Joseph Clark</name></child> <child><name>Taylor Clark</name></child>

</offspring> </family>


</family>

Extend tagging through elements and attributes to improve data accessibilityattributes to improve data accessibility• XML tagging can be extended as data access requirements change:

– For example, you can add a “surname” element to identify the last name for sorting purposes

• Attributes provide information about your data:– Adding an attribute called “gender” to the “child” element allows you to

distinguish boys from girlsdistinguish boys from girls– Examples of possible attribute applications for content:

• Product Name, Product Version, etc.

<?xml version=“1 0”?><?xml version= 1.0 ?><family>

<father><name>Joseph<surname>Clark</surname></name></father><mother><name>Mary <surname>Clark</surname</name></mother><offspring>

<child gender=“girl”><name>Jennifer<surname>Clark</surname></name></child> <child gender=“boy”><name.Joseph <surname>Clark</surname></name></child><child gender=“girl”><name>Taylor<surname>Clark</surname></name></child>

</offspring> </family>


</family>

Does extensibility lead to chaos?

• If XML allows custom elements and attributes, how do we ensure consistency of information and formatting across many authoring groups?groups?

• We define a Document Type Definition (DTD) that allows us to set rules:

Element definitions– Element definitions– Required or not?– Number of elements allowed and whether ordering rules apply

What the elements can contain– What the elements can contain• Other elements• Text• Attributes• Predefined attribute values


The benefits of XML

• XML is a text format that follows an open standard – Is not bound to proprietary authoring tools or formats

– Is platform-independent enabling easy information exchange– Is platform-independent, enabling easy information exchange

• Enables information reuse at the sub-document level– Hierarchical nesting of markup tags creates containers of content within

a documenta document

– Referencing an element includes the information contained within that element, allowing reuse of information at multiple levels of granularity: an entire topic, a set of steps or individual step; a glossary entry (term + p , p p; g y y (definition)

• Separates content from formatting– Different groups/formats can point to the same piece of content without g

reformatting or retagging the information

– Enables dynamic transformation of dataIf XML can do all this, why do we need XML standards for technical documentation?


y

Need for XML standards for technical documentation

• Document-centric XML didn’t grow nearly as fast as data-centric XML. XML standards bodies focused more

d i d don data-centric standards.• Home-built DTDs a challenge

“Companies often spend tens if not hundreds of thousands of dollars developing p p p gcustom DTDs, yet they often turn out to be inflexible and costly to maintain” - JoAnn Hackos, Comtech Services

• Need for more collaborative authoring within and across organizations


XML standards for technical documentation

• Two “popular” open source standards– DocBook

DITA– DITA• Each standard takes fundamentally different approaches• DocBook

– Best suited for linear content: books and articles.– DTD covers all possible authoring requirements. – Does not support truly modular content.pp y– Incomplete reuse and cross-referencing mechanisms– Difficult to customize the DocBook DTD. Customization is

through hiding of elements that are not required.g g

Does DITA solve core documentation challenges?


What is DITA?

• DITA = Darwin Information Typing Architecture• Developed by IBM• Now an OASIS (Organization for the Advancement of

Structured Information Standards) standardCurrent version: 1 1– Current version: 1.1

“We propose the XML-based Darwin Information Typing Architecture (DITA) as an end-to-end architecture for creating and delivering modular technical information.”

— Michael Priestley, IBM


High-Level DITA Architecture

• DITA XML architecture is based on a Topic DTD and a Map DTD

• DITA information architecture is based on topics ─ units of information that serve as building blocks for all contentcontent

• DITA maps assemble topics for specific documentation deliverables


Core design principles of DITA

• Topic orientation– Discrete units of information covering a specific subject with a specific

intent• Topic granularity

– Topics combine with other topics into information sets • Consistencyy

– DITA DTDs guarantee that DITA information types follow identical information structures

• Separation of content (specific topics) from context (links to other topics files navigation)topics, files, navigation)– Not just separation of content from formatting!!

• InheritanceHas a top level “generic” information type from which other types inherit– Has a top-level generic information type from which other types inherit their structures

• Specialization– Ability to extend basic information types for special uses


y yp p

Topics in DITATopics in DITA

Topic: a unit of information that is meaningful when it stands alonestands alone.


About DITA topics

• A chunk of information specific to a single subject.• Short enough to be specific to a single subject or answer

a single question.• Long enough to make sense on its own and be authored

as a unitas a unit.• Each topic must follow the rules for a specific

information type.yp• DITA prescribes three information types:

– ConceptT k– Task

– Reference

• Topic files can have the .dita or .xml extension


p

Information types in DITADITA’s base

information type

Conceptual orConceptual or overview

information Reference information

Procedural, step-by-step

information

Can I have a topic that has a mix of information types?


Why only 3 information types?• Standards like Information Mapping have six information types:

– Procedure– Process– Structure– Concept– Principle– Fact

• IBM itself had 12 information types before DITA:C t l– Conceptual

– Error– General Reference– Glossary– Language Referenceg g– Mapping– Orientation– Sample– Task

Troubleshooting– Troubleshooting– UI Reference– Walkthrough/Tutorial

Why only three information types in DITA?


Why only three information types in DITA?

Why only 3 information types in DITA?

• DITA considers that other information types are basically derivatives of the three core information types: Concept, T k d R fTask and Reference.

• If required, you can customize the core information types to derive other information types using DITAto derive other information types using DITA specialization.

• Bottomline: DITA does not claim to cover all requirements. It covers a base set or requirements and allow other requirements to be covered by extensions.


Concept topics

• Concept topics introduce the background or overview information for task or reference topics.

• Concept topics should not describe task or reference information.

• Concept topics have the restriction that following a• Concept topics have the restriction that following a section or example, only other sections or examples are permitted as content. This ensures that readers are not confused about the content between sections or examples.

• Chunking rule: In a concept topic explain only oneChunking rule: In a concept topic, explain only one concept.


Concept topic structure

<concept><title><titlealts>

<navtitle><searchtitle><shortdesc><prolog><conbody>

<section> | <example><section> | <example><related-links>


Concept topic example


Task topics

• Task topics describe the steps of a particular task, or provide an overview of a higher-level task.

• Task topics should not describe conceptual or reference information.

• Chunking rule: In a task topic describe how to do only• Chunking rule: In a task topic, describe how to do only one task.


Task topic structure

<task><title><titlealts><shortdesc><prolog>p g<taskbody>

<prereq><context><context><steps><result><example><example><postreq>

<related-links>


Task topic example


Reference topics

• Reference topics provide quick access to facts. They describe product features, commands, and so on.

• Information needed for deeper understanding of a reference topic or to perform related procedures should be provided in a concept or task topicbe provided in a concept or task topic.

• Reference topics should be designed for quick scanning of information using lists, tables, and such.

• Reference topics should not describe conceptual or task information.

• Chunking rule: In a reference topic explain only one• Chunking rule: In a reference topic, explain only one subject─for example, explain only one command.


Reference topic structure

<reference><title><titlealts><shortdesc><prolog>p g<refbody>

<example> | <section> | <refsyn> | <table> | <simpletable> | <properties>p p

<related-links>


Reference topic example


Why structure topics by information type?

• Benefits for Writers– Standard, consistent structures for authoring content– Writers can use topic types to more effectively outline information

dneeds– Helps to analyze information according to the purpose or function it

serves for the reader– Organizing common types of information with topics help writers spend

ti f d th i t tmore time focused on authoring content– Choice for selecting the best and most consistent way to present

information, based on information type– Identify missing information– Breaking down information into chunks helps in better planning and

work distribution among writers• Benefits for Users/Readers

– Standard content structure helps readers to quickly identify a topic’sStandard content structure helps readers to quickly identify a topic s purpose

– Readers learn and retain different types of information better when they are written in a consistent, predictable way


DITA Maps

DITA maps assemble topics into a coherent set for documentation deliverablesfor documentation deliverables.


About DITA maps

• Ability to reuse and repurpose the same content for different deliverable types and for deliverables for diff di d ddifferent audiences and products.

• Maps can include DITA topic (.dita) files, XML (.xml), files HTML files PDFs and morefiles, HTML files, PDFs, and more.

• Same topic can be referred to more than once in a map or in different maps.

• Maps can be nested into other maps to build documentation deliverables.

• Maps can be combined together manually or using• Maps can be combined together manually or using scripts during the production process.

• DITA map files have the .ditamap extension.


p p

Different deliverables using DITA maps

Topic 1Quick Start Guide

Topic 2 UserGuide

Topic 3

Reference

Topic 4


Different formats using DITA maps


Map structure

<map><topichead><topicref><reltable><anchor><navref><topicgroup><topicmeta><topicmeta>


DITA Map example

• Example of DITA map in XMetaL


DITA maps do more!!

• Separate of content (specific topics) from context (links to other topics, files, navigation)– Links are specified in the DITA map and not in the topic file itself. Helps topics remain p p p p p

“stand alone”.– Links are automatically generated for the topics from the DITA maps. Helps automatically

update links if topic title or topic file location changes. • Build a relationship table to generate “related topics” links

– Goes beyond sequential orderingGoes beyond sequential ordering– Similar to creating cross references, but moves linking mechanism from content into the

map– Links are generated only in the output version of the topics– Increases reusability—no broken links when taking a piece of content out of context

Sets properties of the topic at a position within the hierarchy• Sets properties of the topic at a position within the hierarchy– Properties include the title and metadata– Can change the topic title relative to the parent topic– Metadata can identify a topic as advanced for one deliverable and basic for another

• Can provide multiple views on the same topics: by product, by task, by topic type,Can provide multiple views on the same topics: by product, by task, by topic type, audience and so on.


Metadata Support in DITA


Metadata support in DITA

• DITA supports a variety of standard and custom metadata:– Author information– Copyright information– Product information– Resource IDs for help systems– Document tracking information

Audience information– Audience information– Keywords– Custom metadata (otherprops)

• Metadata is supported using the <prolog> element in topics and <topicmeta> in maps.

• Metadata at every level !!


• Metadata at every level !!

Metadata elements within <prolog> element

<prolog><author> (name of topic’s author)<copyright><critdates> (document tracking information)<permissions><publisher><source><source><metadata>

<audience> (intended audience)type=“user | purchaser | administrator | … | other”othertype=othertype=job=“installing | customizing | administering | … | other”otherjob=experiencelevel=“novice | general | expert”

<category> (content category used for grouping topics)<category> (content category used for grouping topics)<keywords> (keywords for search engines)<prodinfo><othermeta>


Reuse in DITA


Reuse in DITA

• Reuse flows from the topic-based paradigm– Topics can be reused in different contexts– Topics from multiple components can be integrated as a solution

• Reuse methods– Element-level reuse with <conref>Element level reuse with <conref>– Topic-level reuse with <topicref>– Map-level reuse with <navref> and <anchorref>

C diti l– Conditional reuse


Element level reuse with <conref>

• Conrefs are a way to reference content from the same or another DITA fileExample– Code in source file source.dita:

<step id="commonstep"><cmd>This step exists in a common file and is addedp p pwith a conref.</cmd></step>

– Code in target file B:<step conref=“source.dita#task/commonstep"><cmd></cmd></step>

Note that the <cmd> tags are included even through they will bereplaced by the conreffed information.


Conditional reuse

• DITA gives you four ways of tagging conditionally using AND/OR logic:

Audience– Audience– Platform– Product

Otherprops– OtherpropsExample:The king and queen of Olympus are <ph

di " k">Z </ h>< h di " ">J it </ h>audience="greek">Zeus</ph><ph audience="roman">Jupiter</ph> and <ph audience="greek">Hera</ph><ph audience="roman">Juno</ph>.

When audience=“greek” is set to include this reads– When audience= greek is set to include, this readsThe king and queen of Olympus are Zeus and Hera.

– When audience=“roman” is set to include, this readsThe king and queen of Olympus are Jupiter and Juno.


e g a d quee o O y pus a e Jup te a d Ju o

Specialization in DITA


Topics inherit from DITA’s base “Topic”…

…making it possible to extend through specialization.


Specialization

• Inheritance means that new document structures don’t breakInheritance means that new document structures don t break publishing toolchains

• Specialization can occur in topics, maps, or domains


Specialization: Specializing Topics

• Topic is the core.• Each specialization is a delta in design, and if it needs

special processing that's a delta too.


Specialization: Specializing Maps

• While DITA maps are flexible by default, you can use map specialization to define or enforce a particular type of sequenceof sequence.


Specialization: Specializing Domains• DITA domains extend DITA with a set of elements whose names

and content models are unique to an organization or field of knowledge. For example, you may have elements specific to d ti ftdocumenting software.

• Specialization lets domain-specific elements inherit from existing elements.


DITA Tools


DITA tools

• Modeling tools– IBM Task Modeler-for creating DITA maps

(http://www.alphaworks.ibm.com/tech/taskmodeler)( p p )• Authoring tools

– Arbortext Epic Editor (http://www.ptc.com/)– XMetal (http://www.justsystems.com/)– Syntext Serna (http://www.syntext.com)– FrameMaker 8 with Adobe FrameMaker 8 Plug-in for DITA Open

Toolkit (http://www adobe com/devnet/framemaker/fm8 opentoolkit html)(http://www.adobe.com/devnet/framemaker/fm8_opentoolkit.html)

– DITA Storm (browser-based DITA editor) (http://www.ditastorm.com/onlineDitaEditor.html)

• Production tools– DITA Open Toolkit (http://dita-ot.sourceforge.net/)

• Content management systems– Astoria CMS, EMC Documentum, PTC Windchill, SiberLogic Sibersafe,

V t CMS


Vasont CMS ….

IBM Task Modeler for DITA maps

• IBM was using Rational Rose XDE Developer for content modeling

• Need for a customized modeling tool resulted in the IBM Task Modeler: http://www alphaworks ibm com/tech/taskmodelerhttp://www.alphaworks.ibm.com/tech/taskmodeler

• Eclipse-based plugin for modeling tasks and designing DITA maps


DITA Open Toolkit: the DITA production pipelineP id th th i d d ti i f t t f DITA• Provides the authoring and production infrastructure for DITA.

• Open source: http://dita-ot.sourceforge.net/• Supported outputs:

HTML– HTML– XHTML– Eclipse help– HTML Helpp– Java Help– PDF using XSL-FO


DITA Open Toolkit

• Consists of DTD, XML schema, stylesheets, samples, and documentation for DITA.

• Open source infrastructure • Ant for builds• FOP for XSL-FO to PDF• Xalan or Saxon for XSL-T processing to HTML/xHTML output• Java


DITA Resources


DITA Resources

• DITA Standard OASIS DITA Technical Committee http://www.oasis-

/ i /diopen.org/committees/dita• DITA Articles

– XML Cover Pages: http://xml coverpages org/dita htmlXML Cover Pages: http://xml.coverpages.org/dita.html– DITA Users: http://www.ditausers.org/– http://dita.xml.org

htt // 128 ib /d l k / l/lib / dit 1/– http://www-128.ibm.com/developerworks/xml/library/x-dita1/– http://www.slideshare.net/search/slideshow?q=DITA

• Books on DITA– Introduction to DITA: A User Guide to the Darwin Information

Typing Architecture by Jen Linton and Kylene Bruski, Comtech Services ( http://www.comtech-serv.com/dita.shtml )


( p )

DITA Resources

• DITA Demos / Webinars– FrameMaker 8 Deep Dive: DITA Topic-based authoring

htt // d i d b b t / 227210/ 76122134/https://admin.adobe.acrobat.com/_a227210/p76122134/– <several>

• DITA User Groupsp– http://groups.yahoo.com/group/dita-users/– http://groups.yahoo.com/group/framemaker-dita/

http://dita xml org/user groups– http://dita.xml.org/user-groups


Real life DITA examples

• WebSphere Application Server Documentation http://www-306 ibm com/software/webservers/appserv/was/library/306.ibm.com/software/webservers/appserv/was/library/

• Adobe Creative Suite documentation• Adobe Acrobat documentation• Apache Derby documentation• Eclipse documentation


DITA Demo


Typical DITA workflowUse DITA maps

for content modeling !!

1. Identify the task topics.2. Identify the concept and reference topics needed to

support the task topics.3. Create the topics.4 U DITA t bl t i f h4. Use DITA maps to assemble topics for each

documentation deliverable.5. Publish and deliver the content.5. Publish and deliver the content.

Eclipse helpJavaHelpHTMLHelp

Write BuildArchitectEclipse helpJavaHelpHTMLHelp

Write BuildArchitect Write BuildArchitect

HTMLHelpWeb pagesBooks & PDFsLearning

Information BuildTopics Outputs

HTMLHelpWeb pagesBooks & PDFsLearning

Information BuildTopics OutputsInformation BuildTopics Outputs


Information Architecture

Map

BuildMaps

Topics OutputsInformation Architecture

Map

BuildMaps

Topics OutputsInformation Architecture

Map

BuildMaps

Topics Outputs


Thanks for your participation!!Thanks for your participation!!y p py p p

Technology

DITA Quick Start