IBM Corporate User Technologies
An Introduction to
Darwin Information Typing Architecture: DITA
| February 2004 |
© 2004 IBM Corporation
IBM Corporate User Technologies
Agenda
History of DITA – Why was DITA developed?
Introduction to DITA – What is DITA?
Benefits of DITA – Why should you care?
2
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
What you will hear
 DITA is about making life easier in the realm of
technical writing
• For authors, for editors, for managers, for
collaborators, for information architects, for
developers supporting the teams, for customers
 DITA is about reuse
• Focus on topic authoring based on an information
architecture which supports recombination and
specialization
3
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Background: Why DITA?
4
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
History of markup in IBM
5
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Identify need – Historic convergences within IBM
 IBM task force on information architecture
 Technical writing community focus on Minimalism
 W3C development of XML
 Trend away from SGML (IBMIDDOC)
 Recognized need for alternative
• Shorter development cycles
• Variability in HTML outputs
• Componentization of products
• Need for reuse
6
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Identify the need – Customer issues
 Solutions, not products
• Integration of information
 Information glut
• More meaningful information (role & task based)
 Out-of-date information in books
• Updating and maintaining information
 Reduce cost of deployment of information
• Provide information on-line
 Reduce support costs
• Customize and update information
7
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Identify the need – The Vision (1998/1999)
Single source
XML
topic
1
XML
topic
2
XML
topic
3
Multiple contexts
Information web
A:
1, 2, 3
1
3
2
Print A:
1, 2
2
XML
topic
4
8
Introduction to DITA
Information web
B:
2, 3, 4
4
3
© 2004 IBM Corporation
IBM Corporate User Technologies
Address the problem – Charter XML Work Group
 Appoint technical / thought lead
 Recruit community technical leads
•
Top of line knowledge
•
Top of line passion
 Define charter and scope
 Extend into areas outside ownership to define
boundaries
 Offer competence to others
9
•
Establish thought leadership
•
Develop and enhance analytic skills
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Promise and Reality of XML
 Promise
• Separate content from form: reuse content in different presentation
media
• Use specific markup to describe your content
• Use standard solution to enable easy exchange of information
 Reality – Generic XML
• Generic XML provides an SGML with simpler syntax but similar
problems
• Generic solutions - not specific to needs
• Knowledge representation is strongly related to current corporate
culture
 Tradeoff
• The more useful your markup is to you, the more it will cost you and
the fewer people will share the costs
10
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
DITA designed to address trade-offs
What is DITA?
11
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
DITA defined
 Darwin: DITA utilizes principles of inheritance
for specialization
 Information Typing: DITA was originally
designed for technical information based on an
information architecture of Concept, Task and
Reference
 Architecture: DITA is a model for extension
both of design and of processes
12
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Core design principles of DITA
 Topic orientation
• Discrete units of information covering a specific subject with a
specific intent
 Topic granularity
• Self-contained topics combine with other topics into
information sets
 Strong typing
• DTDs and schemas guarantee that DITA types follow identical
information structures
 Specialization
• Architecture for extending basic types to new types adapted
for a particular use within an information set
 Common base class
• Top-level "generic" base type provides “fallback” for all types
13
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
The core DITA topic types – The “IT” in DITA
topic
A unit of information which is
meaningful when it stands
alone.
concept
Provides background information
that users need to know .
14
Introduction to DITA
task
Provides procedural details such as
step-by-step instructions.
reference
Provides quick access to facts.
© 2004 IBM Corporation
IBM Corporate User Technologies
DITA and reuse
15
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Reuse of content
 Reuse flows from the topic-based paradigm
 If content is authored as standalone topics
• Topics can be reused in different
contexts
• Topics from multiple components can be
integrated as a solution
16
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Working with DITA maps
Eclipse help
JavaHelp
HTMLHelp
web pages
books
17

A DITA map applies context to the topics

Organizes a set of topics in a hierarchy and sequence
Different organization for different deliverables — not just different formats for the
same content
Can reuse the same topic with different collections of topics
Can provide multiple views on the same topics: by product, by task, …

Sets properties of the topic at a position within the hierarchy
Properties include the title and metadata
Change the title relative to the parent topic
Metadata can identify a topic as advanced for one deliverable and basic for another
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Reuse of design
 General types are rarely enough
• Requirements specific to organization or industry
 Meet requirements with new elements
• New element specializes existing element
• New content is a subset of base content
 Add only the deltas - still use the base
 Designs are modular
• For instance, optional b and i highlighting
18
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Specializing from Topic to Task
topic
task
title
title
prolog
prolog
metadata
body
taskbody
related-links
related-links
Small DTD additions to
enforce document structure.
May have no CSS or XSL
process changes.
19
metadata
Introduction to DITA
prereq
result
context
taskxmp
example
steps
postreq
step
cmd,
cmd,
(info
(info
| substeps
| substeps
| tutorialinfo
| tutorialinfo
| stepxmp
|
|xmp
choices|choicetable)*,
| choices)*, result? stepresult?
© 2004 IBM Corporation
IBM Corporate User Technologies
From Task to Business Task
task
businesstask
title
title
prolog
prolog
metadata
metadata
taskbody
btaskbody
related-links
related-links
prereq
result
prereq
result
context
taskxmp
example
context
example
steps
postreq
bsteps
postreq
step
cmd,
cmd,
(info
(info
| substeps
| substeps
| tutorialinfo
| tutorialinfo
| stepxmp
|
|xmp
choices|choicetable)*,
| choices)*, result? stepresult?
20
Additional
structure
changes.
Introduction to DITA
step
appstep
appdesc
© 2004 IBM Corporation
IBM Corporate User Technologies
Specializations from Topic
Topic
Reference
Task
Concept
minitask
bctask
manpages
UI help
APIs
Messages
Topic is the core.
Each specialization is a delta in design,
and if it needs special processing that's a
delta too.
21
Introduction to DITA
Java APIs
C++ APIs
© 2004 IBM Corporation
IBM Corporate User Technologies
Benefit of design reuse through specialization
 No need to reinvent the base vocabulary - Create a module in 1/2 day with 10 lines vs. 6
months with 100s of lines; automatically pick up changes to the base
 No impact from other designs that customize for different purposes - Avoid enormous,
kitchen-sink vocabularies; Plug in the modules for your requirements
 Interoperability at the base type - Guaranteed reversion from special to base
 Reusable type hierarchies - Share understanding of information across groups, saving time and
presenting a consistent picture to customers
 Output tailored to customers and information - More specific search, filtering, and reuse that
is designed for your customers and information not just the common denominator
 Consistency - Both with base standards and within your information set
 Learning support for new writers - Instead of learning standard markup plus specific ways to
apply the markup, writers get specific markup with guidelines built in
 Explicit support of different product architectural requirements - Requirements of different
products and architectures can be supported and enforced, rather than suggested and monitored by
editorial staff
22
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Reuse of processes
 Base processing in extensible XSLT
 Standard processing can be customized
• Override standard processing as needed
 Processes for base elements apply to new
specialized elements by default
• Can use base processing
• Can write custom processing if needed
23
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Specialized processes
Specialized processes handle the delta for specialized topic types
Base and delta DTDs
Base and delta processors
Base
topic
Base processors
Task
bcTask
Concept
Specialization-specific
processors
Reference
bcReference
24
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Summary
25
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Summary of reuse
 Reuse content through topics
• Author content as standalone information
 Reuse designs through specialization
• Meet requirements specific to organization
• Keep interoperability with others
 Reuse processing
• Customize only as needed
26
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Summary Benefits and Problems Solved
Development challenges met
•
Shorter development cycles
•
Eliminate variability in HTML outputs
•
Support componentization of products and need for reuse
Deliver solution information, not product information
•
Integration of information
Information glut
•
More meaningful information (role & task based)
Out-of-date information in books
•
Updating and maintaining information
Reduce cost of deployment of information
•
Provide information on-line
Reduce support costs
•
27
Customize and update information
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Backup Slides
28
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Epic Editor
with DITA
Maps
Manage
hierarchy
Create new &
edit
Preview HTML &
PDF
Check out
29
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technologies
Epic Editor
with DITA
Topics
Content edit
Common
elements
Indexing,
linking helpers
30
Introduction to DITA
© 2004 IBM Corporation
IBM Corporate User Technology
DITA topic example
<task id="installstorage">
<title>Installing a hard drive</title>
<shortdesc>You open the box and insert the drive.</shortdesc>
<prolog><metadata>
<audience type="administrator"/>
<keywords>
<indexterm>hard drive</indexterm>
<indexterm>disk drive</indexterm>
</keywords>
</metadata></prolog>
<taskbody>
<steps>
<step><cmd>Unscrew the cover.</cmd>
<stepresult>The drive bay is exposed.</stepresult>
</step>
<step><cmd>Insert the drive into the drive bay.</cmd>
<info>If you feel resistance, try another angle.</info>
</step>
</steps>
</taskbody>
<related-links>
<link href="formatstorage.dita"/>
<link href="installmemory.dita"/>
</related-links>
</task>
An Introduction to DITA
Identifier, title,
and shortdesc
Properties of
the topic
Type-specific
content body
Relationships
to other topics
© 2004 IBM Corporation
IBM Corporate User Technology
DITA map example
<map title="Tasks">
<topichead navtitle="Installing"
audience="admin">
<topicmeta>
<shortdesc>Install products before
configuring or using them.</shortdesc>
<topicmeta>
<topicref href="installstorage.dita">
<topicref href="unscrewcover.dita"/>
<topicref href="insertdrive.dita"/>
<topicref href="replacecover.dita"/>
</topicref>
<topicref href="installwebserver.dita">
<topicref href="closeprograms.dita"/>
<topicref href="runsetup.dita"/>
<topicref href="restart.dita"/>
</topicref>
<topicref href="installdb.dita">
<topicref href="closeprograms.dita"/>
<topicref href="runsetup.dita"/>
<topicref href="restart.dita"/>
</topicref>
</topichead>
…
</map>
An Introduction to DITA
A heading doesn’t have to
have a topic
Title and properties can be
assigned in the map
The map organizes a set of
topics in a hierarchy
A topic can appear multiple
times in the hierarchy
© 2004 IBM Corporation