DITA 101

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

http://www.scriptorium.com

http://www.scriptorium.com

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> Red tag, blue tag Black tag, blue tag, old tag, new tag This one has a little car This one has a little star <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>

Aardvarks eat mostly termites. 

Do not accept the aardvarks' offer to helpdeal with your termite problem. You will not like the results.

<note type="danger" id="nofeeding">Do not feed animals snacks, scraps, or people food.</note>

</body>

</topic>





<body>




</body>

</topic>

I am XML.





<body>




</body>

</topic>

I am a DITA topic.





<body>




</body>

</topic>





<body>




</body>

</topic>





<body>




</body>

</topic>





<body>




</body>

</topic>

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>







</topicref></map>

I am a DITA map.







</topicref></map>







</topicref></map>







</topicref></map>







</topicref></map>

Level 1







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

Baboons eat mostly fruit.

<note conref="Aardvark.xml#aardvark/nofeeding"/>

</body></topic>

Named destination in Aardvark.xml

Link in Baboon.xml





</body></topic>


Link in Baboon.xml





</body></topic>


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?

Technology

DITA 101