Gone through articles and presentations on the web and got a half-baked understanding of the Darwin Information Typing Architecture (DITA)? Refer to my DITA Quick Start presentation for the 2007 STC India Conference to learn to evaluate, plan and start implementing DITA. In this presentation, you will learn about the following: o Structured authoring and XML o Key DITA concepts: topics, maps, specialization o DITA architecture and content model o Authoring in topics o Organizing content using DITA maps o Creating relationship tables o Conditional text and reuse in DITA o Metadata support in DITA o DITA tools, standards and processes o Publishing with the DITA Open Toolkit

1. DITA Quick Start
Selvakumar T.S
1 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

2. Agenda
• A quick look at XML
• Understand DITA’s overall approach
• Understand DITA’s core content structures and how you
can customize them
• U d t d th scope f reuse i DITA
Understand the for in
• See DITA at work!!
2 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

3. A Quick Look at XML
3 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

4. 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 y
users to define their own tags.
XML is like
a
database!!
HTML Example XML Example
<ul> <family>
<li>Joseph Clark</li>
p <father><name>Joseph Clark</name></father>
<li>Mary Clark </li> <mother><name>Mary Clark</name></mother>
<offspring>
<li>Jennifer Clark</li>
<child><name>Jennifer Clark</name></child>
<li>Joseph C a II</li>
Josep Clark /
<child><name>Joseph Clark</name></child>
<li>Taylor Clark</li>
<child><name>Taylor Clark</name></child>
</ul> </offspring>
</family>
4 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

5. Extend tagging through elements and
attributes 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 girls
– Examples of possible attribute applications for content:
• Product Name, Product Version, etc.
<?xml version= 1.0 ?>
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>
5 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

6. 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?
• We define a Document Type Definition (DTD) that allows us to set
rules:
– Element definitions
– Required or not?
– Number of elements allowed and whether ordering rules apply
– What the elements can contain
• Other elements
• Text
• Attributes
• Predefined attribute values
6 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

7. 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
platform-independent
• Enables information reuse at the sub-document level
– Hierarchical nesting of markup tags creates containers of content within
a 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 g
p , p p; glossary entry (
y y (term +
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 data
If XML can do all this, why do we need XML standards for technical documentation?
y
7 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

8. 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
on d
data-centric standards.
i d d
• Home-built DTDs a challenge
“Companies often spend tens if not hundreds of thousands of dollars developing
p p p g
custom 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
8 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

9. XML standards for technical documentation
• Two “popular” open source standards
– DocBook
– 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?
9 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

10. What is DITA?
• DITA = Darwin Information Typing Architecture
• Developed by IBM
• Now an OASIS (Organization for the Advancement of
Structured Information Standards) standard
– Current version: 1 1
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
10 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

11. 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
content
• DITA maps assemble topics for specific documentation
deliverables
11 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

12. 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
• Consistency
y
– DITA DTDs guarantee that DITA information types follow identical
information structures
• Separation of content (specific topics) from context (links to other
topics, files,
topics files navigation)
– Not just separation of content from formatting!!
• Inheritance
– Has a top level “generic” information type from which other types inherit
top-level generic
their structures
• Specialization
– Ability to extend basic information types for special uses
y yp p
12 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

13. Topics in DITA
Topic: a unit of information that is meaningful when it
stands alone
alone.
13 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

14. 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 unit
unit.
• Each topic must follow the rules for a specific
information type.
yp
• DITA prescribes three information types:
– Concept
– T k
Task
– Reference
• Topic files can have the .dita or .xml extension
p
14 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

15. Information types in DITA
DITA’s base
information type
Conceptual or
overview
information Reference
information
Procedural, step- Can I have a topic that has a
by-step
information mix of information types?
15 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

16. 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:
– Conceptual
C t l
– Error
– General Reference
– Glossary
– Language Reference
g g
– Mapping
– Orientation
– Sample
– Task
– Troubleshooting
– UI Reference
– Walkthrough/Tutorial
Why only three information types in DITA?
16 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

17. Why only 3 information types in DITA?
• DITA considers that other information types are basically
derivatives of the three core information types: Concept,
Task d R f
T k and Reference.
• If required, you can customize the core information types
to 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.
17 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

18. 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
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 one
topic
concept.
18 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

19. Concept topic structure
<concept>
<title>
<titlealts>
<navtitle><searchtitle>
<shortdesc>
<prolog>
<conbody>
<section> | <example>
<related-links>
19 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

20. Concept topic example
20 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

21. 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
topic,
one task.
21 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

22. Task topic structure
<task>
<title>
<titlealts>
<shortdesc>
<prolog>
p g
<taskbody>
<prereq>
<context>
<steps>
<result>
<example>
<postreq>
<related-links>
22 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

23. Task topic example
23 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

24. 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 topic
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
topic,
subject─for example, explain only one command.
24 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

25. Reference topic structure
<reference>
<title>
<titlealts>
<shortdesc>
<prolog>
p g
<refbody>
<example> | <section> | <refsyn> | <table> | <simpletable> |
<properties>
p p
<related-links>
25 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

26. Reference topic example
26 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

27. 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
needs
d
– 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
more ti
time f
focused on authoring content
d th i t t
– 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’s
topic s
purpose
– Readers learn and retain different types of information better when they
are written in a consistent, predictable way
27 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

28. DITA Maps
DITA maps assemble topics into a coherent set
for documentation deliverables
deliverables.
28 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

29. About DITA maps
• Ability to reuse and repurpose the same content for
different deliverable types and for deliverables for
different audiences and products.
diff di d d
• Maps can include DITA topic (.dita) files, XML (.xml),
files,
files HTML files PDFs and more
files, PDFs, 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
scripts during the production process.
• DITA map files have the .ditamap extension.
p p
29 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

30. Different deliverables using DITA maps
Quick
Topic 1 Start
Guide
Topic 2
User
Guide
Topic 3
Reference
Topic 4
30 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

31. Different formats using DITA maps
31 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

32. Map structure
<map>
<topichead>
<topicref>
<reltable>
<anchor>
<navref>
<topicgroup>
<topicmeta>
32 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

33. DITA Map example
• Example of DITA map in XMetaL
33 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

34. 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 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
– 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,
audience and so on.
34 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

35. Metadata Support in DITA
35 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

36. 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
– Keywords
– Custom metadata (otherprops)
• Metadata is supported using the <prolog> element in
topics and <topicmeta> in maps.
• Metadata at every level !!
36 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

37. Metadata elements within <prolog> element
<prolog>
<author> (name of topic’s author)
<copyright>
<critdates> (document tracking information)
<permissions>
<publisher>
<source>
<metadata>
<audience> (intended audience)
type=“user | purchaser | administrator | … | other”
othertype=
job=“installing | customizing | administering | … | other”
otherjob=
experiencelevel=“novice | general | expert”
<category> (content category used for grouping topics)
<keywords> (keywords for search engines)
<prodinfo>
<othermeta>
37 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

38. Reuse in DITA
38 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

39. 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
Element-level reuse with <conref>
– Topic-level reuse with <topicref>
– Map-level reuse with <navref> and <anchorref>
– Conditional reuse
C diti l
39 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

40. Element level reuse with <conref>
• Conrefs are a way to reference content from the same or
another DITA file
Example
– Code in source file source.dita:
<step id="commonstep"><cmd>This step exists in a common file and is added
p p p
with 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 be
replaced by the conreffed information.
40 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

41. Conditional reuse
• DITA gives you four ways of tagging conditionally using AND/OR
logic:
– Audience
– Platform
– Product
– Otherprops
Example:
The king and queen of Olympus are <ph
audience="greek">Zeus</ph><ph audience="roman">Jupiter</ph>
di " k">Z </ h>< h di " ">J it </ h>
and <ph audience="greek">Hera</ph><ph
audience="roman">Juno</ph>.
– When audience= greek is set to include this reads
audience=“greek” include,
The king and queen of Olympus are Zeus and Hera.
– When audience=“roman” is set to include, this reads
The king a d quee o O y pus a e Jup te a d Ju o
e g and queen of Olympus are Jupiter and Juno.
41 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

42. Specialization in DITA
42 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

43. Topics inherit from DITA’s base “Topic”…
…making it possible to extend through specialization.
43 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

44. Specialization
• Inheritance means that new document structures don’t break
don t
publishing toolchains
• Specialization can occur in topics, maps, or domains
44 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

45. 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.
45 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

46. Specialization: Specializing Maps
• While DITA maps are flexible by default, you can use
map specialization to define or enforce a particular type
of sequence.
sequence
46 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

47. 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
documenting software.
d ti ft
• Specialization lets domain-specific elements inherit from existing
elements.
47 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

48. DITA Tools
48 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

49. DITA tools
• Modeling tools
– IBM Task Modeler-for creating DITA maps
( p
(http://www.alphaworks.ibm.com/tech/taskmodeler)
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,
Vasont CMS ….
V t
49 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

50. 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/taskmodeler
http://www alphaworks ibm com/tech/taskmodeler
• Eclipse-based plugin for modeling tasks and designing
DITA maps
50 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

51. DITA Open Toolkit: the DITA production pipeline
• Provides the th i
P id th authoring and production i f t t
d d ti infrastructure f DITA
for DITA.
• Open source: http://dita-ot.sourceforge.net/
• Supported outputs:
– HTML
– XHTML
– Eclipse help
– HTML Help p
– Java Help
– PDF using XSL-FO
51 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

52. 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
52 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

53. DITA Resources
53 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

54. DITA Resources
• DITA Standard
OASIS DITA Technical Committee http://www.oasis-
open.org/committees/dita
/ i /di
• DITA Articles
– XML Cover Pages: http://xml coverpages org/dita html
http://xml.coverpages.org/dita.html
– DITA Users: http://www.ditausers.org/
– http://dita.xml.org
– http://www-128.ibm.com/developerworks/xml/library/x-dita1/
htt // 128 ib /d l k / l/lib / dit 1/
– 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
54 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

55. DITA Resources
• DITA Demos / Webinars
– FrameMaker 8 Deep Dive: DITA Topic-based authoring
https://admin.adobe.acrobat.com/_a227210/p76122134/
htt // d i d b b t / 227210/ 76122134/
– <several>
• DITA User Groups
p
– 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
55 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

56. 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
56 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

57. DITA Demo
57 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

58. Use DITA maps
for content
Typical DITA workflow modeling !!
1. Identify the task topics.
2. Identify the concept and reference topics needed to
support the task topics.
3. Create the topics.
4. Use
4 U DITA maps to assemble t i f each
t bl topics for h
documentation deliverable.
5. Publish and deliver the content.
Architect Write Build
Eclipse help
JavaHelp
HTMLHelp
Web pages
Books & PDFs
Learning
Information Topics Build Outputs
Architecture Maps
Map
58 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

59. 59 August 9, 2009 Cadence Confidential: Cadence Internal Use Only

60. Thanks for your p
y participation!!
p