DITA 101
Sarah O’Keefe (@sarahokeefe)Scriptorium Publishing (@Scriptorium)
Sarah O’Keefe @sarahokeefe❖ Founder and president, Scriptorium
Publishing, www.scriptorium.com
❖ Based in North Carolina
❖ Content strategy for tech comm
❖ Interested in collision of content, publishing, and technology
Before we begin…
❖ Everyone is muted except for the presenter
❖ Please ask your questions through the Questions area in the webcast interface
❖ The presentation is being recorded; attendees do not appear in the recording
❖ #dita101 hashtag for Twitter
Agenda
❖ What is DITA?
❖ Key DITA concepts
❖ Typical scenarios for DITA
❖ Is DITA right for you?
What is DITA?
❖ Darwin Information Typing Architecture
❖ Darwin – because you can evolve new elements from existing elements
❖ Information Typing – content is categorized as task, reference, concept
❖ Architecture – includes components for reuse, single sourcing, and generating output
❖ Developed by IBM, maintained by OASIS
Why is DITA important? Is DITA important?❖ Structured authoring is creating content
with programmatic enforcement of the required structure
❖ DITA is a specific way to do structured authoring
❖ Many software vendors support DITA
What is DITA, really?
❖ XML standard
❖ Built for topic-oriented authoring
❖ A way to work in XML without having to design your own structure?
❖ A major buzzword in tech comm
❖ Cost-effective way to create, publish, reuse, and exchange structured content
DITA components
❖ Document type definitions (DTDs, which define structure)
❖ Open Toolkit for generating output
❖ HTML, Eclipse help, CHM, and others through XSL
❖ PDF through XSL-FO
❖ Documentation
DITA publishing
WhatDITA is not
flickr: JoelK75
flickr: bandita
Perhaps it’s this…
flickr: erix!
Is DITA better than XML?
flickr: matthewreid
flickr: eliduke, mdpettitt
Which is better?
Context matters. flickr: NeilsPhotography
flickr: liamq
DITA’s ideal habitat
❖ Topic-oriented, modular content
❖ Content reuse
❖ Content exchange
❖ Translation/localization workflow
Most common business case for DITA?❖ Localization cost savings
❖ Reuse
DITA’s challenges
❖ Automated formatting versus hand-crafted pagination
❖ Narrative content
❖ High level of technical expertise required
❖ New skills for authors
DITA topic (simplified)
<topic id=”seuss”>
<title>One tag, two tag</title> <body> <p>Red tag, blue tag</p> <p>Black tag, blue tag, old tag, new tag</p> <p>This one has a little car</p> <p>This one has a little star</p> <note>Say, what a lot of tags there are!</note> </body></topic>
<?xml version="1.0"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="aardvark" audience="internal">
<title>Aardvark</title>
<body>
<p>Aardvarks eat mostly termites. </p>
<p>Do not accept the aardvarks' offer to helpdeal with your termite problem. You will <b>not</b> like the results.</p>
<note type="danger" id="nofeeding">Do not feed animals snacks, scraps, or people food.</note>
</body>
</topic>
<?xml version="1.0"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="aardvark" audience="internal">
<title>Aardvark</title>
<body>
<p>Aardvarks eat mostly termites. </p>
<p>Do not accept the aardvarks' offer to helpdeal with your termite problem. You will <b>not</b> like the results.</p>
<note type="danger" id="nofeeding">Do not feed animals snacks, scraps, or people food.</note>
</body>
</topic>
I am XML.
<?xml version="1.0"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="aardvark" audience="internal">
<title>Aardvark</title>
<body>
<p>Aardvarks eat mostly termites. </p>
<p>Do not accept the aardvarks' offer to helpdeal with your termite problem. You will <b>not</b> like the results.</p>
<note type="danger" id="nofeeding">Do not feed animals snacks, scraps, or people food.</note>
</body>
</topic>
I am a DITA topic.
<?xml version="1.0"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="aardvark" audience="internal">
<title>Aardvark</title>
<body>
<p>Aardvarks eat mostly termites. </p>
<p>Do not accept the aardvarks' offer to helpdeal with your termite problem. You will <b>not</b> like the results.</p>
<note type="danger" id="nofeeding">Do not feed animals snacks, scraps, or people food.</note>
</body>
</topic>
<?xml version="1.0"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="aardvark" audience="internal">
<title>Aardvark</title>
<body>
<p>Aardvarks eat mostly termites. </p>
<p>Do not accept the aardvarks' offer to helpdeal with your termite problem. You will <b>not</b> like the results.</p>
<note type="danger" id="nofeeding">Do not feed animals snacks, scraps, or people food.</note>
</body>
</topic>
<?xml version="1.0"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="aardvark" audience="internal">
<title>Aardvark</title>
<body>
<p>Aardvarks eat mostly termites. </p>
<p>Do not accept the aardvarks' offer to helpdeal with your termite problem. You will <b>not</b> like the results.</p>
<note type="danger" id="nofeeding">Do not feed animals snacks, scraps, or people food.</note>
</body>
</topic>
<?xml version="1.0"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="aardvark" audience="internal">
<title>Aardvark</title>
<body>
<p>Aardvarks eat mostly termites. </p>
<p>Do not accept the aardvarks' offer to helpdeal with your termite problem. You will <b>not</b> like the results.</p>
<note type="danger" id="nofeeding">Do not feed animals snacks, scraps, or people food.</note>
</body>
</topic>
WYSIOOWhat You See Is…One Option
WYSIOOWhat You See Is…One Option
WYSIOOWhat You See Is…One Option
WYSIOOWhat You See Is…One Option
Key DITA concepts
❖ Topics
❖ Map files
❖ Content references (conrefs)
❖ Specialization
Topics
flickr: scientificquilter
Map files
flickr: acnatta
<?xml version="1.0"?><!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"><map rev="1" title="Zoo Policies" xml:lang="en-us"><topicmeta>
<author>Sarah</author><critdates> <created date="2006/10/31"/> <revised modified="2012/05/31"/>
</critdates></topicmeta><topicref href="Animal_nutrition.xml" navtitle="Animal nutrition" type="reference">
<topicref href="Aardvark.xml" navtitle="Aardvark" type="topic"/><topicref href="Baboon.xml" navtitle="Baboon" type="topic"/><topicref href="Crane.xml" navtitle="Crane" type="topic"/><topicref href="Dingo.xml" navtitle="Dingo" type="topic"/>
</topicref><topicref href="Visitor_behavior.xml" navtitle="Visitor behavior" type="topic">
<topicref href="Adults.xml" navtitle="Adults" type="topic"/><topicref href="Children.xml" navtitle="Children" type="topic"/>
</topicref></map>
<?xml version="1.0"?><!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"><map rev="1" title="Zoo Policies" xml:lang="en-us"><topicmeta>
<author>Sarah</author><critdates> <created date="2006/10/31"/> <revised modified="2012/05/31"/>
</critdates></topicmeta><topicref href="Animal_nutrition.xml" navtitle="Animal nutrition" type="reference">
<topicref href="Aardvark.xml" navtitle="Aardvark" type="topic"/><topicref href="Baboon.xml" navtitle="Baboon" type="topic"/><topicref href="Crane.xml" navtitle="Crane" type="topic"/><topicref href="Dingo.xml" navtitle="Dingo" type="topic"/>
</topicref><topicref href="Visitor_behavior.xml" navtitle="Visitor behavior" type="topic">
<topicref href="Adults.xml" navtitle="Adults" type="topic"/><topicref href="Children.xml" navtitle="Children" type="topic"/>
</topicref></map>
I am a DITA map.
<?xml version="1.0"?><!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"><map rev="1" title="Zoo Policies" xml:lang="en-us"><topicmeta>
<author>Sarah</author><critdates> <created date="2006/10/31"/> <revised modified="2012/05/31"/>
</critdates></topicmeta><topicref href="Animal_nutrition.xml" navtitle="Animal nutrition" type="reference">
<topicref href="Aardvark.xml" navtitle="Aardvark" type="topic"/><topicref href="Baboon.xml" navtitle="Baboon" type="topic"/><topicref href="Crane.xml" navtitle="Crane" type="topic"/><topicref href="Dingo.xml" navtitle="Dingo" type="topic"/>
</topicref><topicref href="Visitor_behavior.xml" navtitle="Visitor behavior" type="topic">
<topicref href="Adults.xml" navtitle="Adults" type="topic"/><topicref href="Children.xml" navtitle="Children" type="topic"/>
</topicref></map>
<?xml version="1.0"?><!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"><map rev="1" title="Zoo Policies" xml:lang="en-us"><topicmeta>
<author>Sarah</author><critdates> <created date="2006/10/31"/> <revised modified="2012/05/31"/>
</critdates></topicmeta><topicref href="Animal_nutrition.xml" navtitle="Animal nutrition" type="reference">
<topicref href="Aardvark.xml" navtitle="Aardvark" type="topic"/><topicref href="Baboon.xml" navtitle="Baboon" type="topic"/><topicref href="Crane.xml" navtitle="Crane" type="topic"/><topicref href="Dingo.xml" navtitle="Dingo" type="topic"/>
</topicref><topicref href="Visitor_behavior.xml" navtitle="Visitor behavior" type="topic">
<topicref href="Adults.xml" navtitle="Adults" type="topic"/><topicref href="Children.xml" navtitle="Children" type="topic"/>
</topicref></map>
<?xml version="1.0"?><!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"><map rev="1" title="Zoo Policies" xml:lang="en-us"><topicmeta>
<author>Sarah</author><critdates> <created date="2006/10/31"/> <revised modified="2012/05/31"/>
</critdates></topicmeta><topicref href="Animal_nutrition.xml" navtitle="Animal nutrition" type="reference">
<topicref href="Aardvark.xml" navtitle="Aardvark" type="topic"/><topicref href="Baboon.xml" navtitle="Baboon" type="topic"/><topicref href="Crane.xml" navtitle="Crane" type="topic"/><topicref href="Dingo.xml" navtitle="Dingo" type="topic"/>
</topicref><topicref href="Visitor_behavior.xml" navtitle="Visitor behavior" type="topic">
<topicref href="Adults.xml" navtitle="Adults" type="topic"/><topicref href="Children.xml" navtitle="Children" type="topic"/>
</topicref></map>
<?xml version="1.0"?><!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"><map rev="1" title="Zoo Policies" xml:lang="en-us"><topicmeta>
<author>Sarah</author><critdates> <created date="2006/10/31"/> <revised modified="2012/05/31"/>
</critdates></topicmeta><topicref href="Animal_nutrition.xml" navtitle="Animal nutrition" type="reference">
<topicref href="Aardvark.xml" navtitle="Aardvark" type="topic"/><topicref href="Baboon.xml" navtitle="Baboon" type="topic"/><topicref href="Crane.xml" navtitle="Crane" type="topic"/><topicref href="Dingo.xml" navtitle="Dingo" type="topic"/>
</topicref><topicref href="Visitor_behavior.xml" navtitle="Visitor behavior" type="topic">
<topicref href="Adults.xml" navtitle="Adults" type="topic"/><topicref href="Children.xml" navtitle="Children" type="topic"/>
</topicref></map>
Level 1
<?xml version="1.0"?><!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"><map rev="1" title="Zoo Policies" xml:lang="en-us"><topicmeta>
<author>Sarah</author><critdates> <created date="2006/10/31"/> <revised modified="2012/05/31"/>
</critdates></topicmeta><topicref href="Animal_nutrition.xml" navtitle="Animal nutrition" type="reference">
<topicref href="Aardvark.xml" navtitle="Aardvark" type="topic"/><topicref href="Baboon.xml" navtitle="Baboon" type="topic"/><topicref href="Crane.xml" navtitle="Crane" type="topic"/><topicref href="Dingo.xml" navtitle="Dingo" type="topic"/>
</topicref><topicref href="Visitor_behavior.xml" navtitle="Visitor behavior" type="topic">
<topicref href="Adults.xml" navtitle="Adults" type="topic"/><topicref href="Children.xml" navtitle="Children" type="topic"/>
</topicref></map>
Level 1
Level 2
conrefs <topic id="aardvark">...<note type="danger" id="nofeeding">Do not feed animals snacks, scraps, or people food. …</topic>
<topic id="baboon"><title>Baboon</title><body>
<p>Baboons eat mostly fruit.</p><p>
<note conref="Aardvark.xml#aardvark/nofeeding"/></p>
</body></topic>
Named destination in Aardvark.xml
Link in Baboon.xml
conrefs <topic id="aardvark">...<note type="danger" id="nofeeding">Do not feed animals snacks, scraps, or people food. …</topic>
<topic id="baboon"><title>Baboon</title><body>
<p>Baboons eat mostly fruit.</p><p>
<note conref="Aardvark.xml#aardvark/nofeeding"/></p>
</body></topic>
Named destination in Aardvark.xml
Link in Baboon.xml
conrefs <topic id="aardvark">...<note type="danger" id="nofeeding">Do not feed animals snacks, scraps, or people food. …</topic>
<topic id="baboon"><title>Baboon</title><body>
<p>Baboons eat mostly fruit.</p><p>
<note conref="Aardvark.xml#aardvark/nofeeding"/></p>
</body></topic>
Named destination in Aardvark.xml
Link in Baboon.xml
Specialization
❖ Lets you create additional elements without breaking DITA Open Toolkit processing.
❖ New element is a specialization of the base element.
❖ This is what put the D in DITA.
Customizationoptions
flickr: munksynz
Customization
Constraints
Specialization
Business case for XML
❖ Content exchange
❖ Database publishing
❖ Reuse content/reduce duplication
❖ Automated formatting/publishing
❖ Compliance
Beyond XML’s business case, DITA may…❖ Reduce content modeling effort
❖ Make content truly portable
❖ Support content reuse
❖ Take advantage of software support
❖ Provide output options
❖ Reduce overall cost of implementation
Reduce content modeling effort
Make content truly portable
flickr: aloha75
Support content reuse
❖ Map files
❖ conrefs (and variations)
❖ keyrefs (and variations)
Software support
❖ DITA support found in many (most?) XML authoring tools
❖ Some tools support only DITA and not general XML
Provide output options
❖ XHTML, HTML Help, PDF, Eclipse, DocBook, JavaHelp, troff, Word RTF through DITA Open Toolkit
❖ Starting point for output
❖ Not suitable for production workflow
❖ Customization is difficult and time-consuming
Is DITA right for you?
flickr: nugunslinger
Yes
❖ DITA meets all requirements.
❖ A business partner or customer requires DITA content.
❖ Single sourcing is a requirement.
❖ No existing content.
❖ Can be flexible with markup requirements to make implementation faster.
No.
❖ Content must conform to a specific standard, such as S1000D.
❖ Content is and should remain narrative.
❖ Semantic requirements are industry-specific, complex, and/or strict.
❖ No possibility of internal or external support for technical challenges.
Maybe.
❖ DITA is not an exact match.
❖ Customization/specialization would be required.
Questions?