IBM Corporate User Technologies January 10, 2005 © 2004 IBM Corporation An Introduction to Darwin Information Typing Architecture: DITA Don Day, Chair,

IBM Corporate User Technologies

January 10, 2005 © 2004 IBM Corporation

An Introduction to Darwin Information Typing Architecture: DITA

Don Day, Chair, OASIS DITA Technical CommitteeIBM Lead DITA ArchitectPresented to OASIS Business Centric Methodology Technical Committee


Introduction to DITA © 2004 IBM Corporation2

AgendaAgenda

History of DITA – Why was DITA developed?

Introduction to DITA – What is DITA?

Benefits of DITA – Why should you care?



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



Background: Why DITA?Background: Why DITA?



History of markup in IBM

Limited reuseSingle purpose

1970s:ISIL

Printed books

1980s:BookMaster,

IPF

Printed and online books, online help

One book-centered DTDInformation architecture

1990s:SGML, HTML

Online information, webs, printable &

printed books

Need for change in 1990s

Components, multiplatform, open

systems

Web-deployed products and informationPartner and OEM use of information

2000+XML-based semantics

Alternatives to books

Shorter cycles, fewer people versus monolithic DTDs, long learning curves. Need for faster, cheaper. Reuse.



Identify the need – Historic convergences within IBM

Initiation of an IBM task force on information architecture

Focus by technical writing community on Minimalism

Development of XML by World Wide Web Consortium (W3C)

Trend away from SGML-era design thoughts (IBMIDDoc DTD)

Recognized need for alternative that would provide:• Shorter development cycles

• Variability in HTML outputs

• Componentization of products

• Reuse of common information components



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 integrated or on-line

Reduce support costs• Customize and update information



Identify the need – The Vision (1998/1999)

Single source

XML topic

1

XML topic

2

XML topic

3

XML topic

4

1

2

3

2

3

4

Multiple contexts

Information web A:

1, 2, 3

Print A:1, 2

Information web B:

2, 3, 4



Address the problem – Charter XML Work Group

Appointed a technical / thought lead Recruited a community of technical leads

• Top of line knowledge

• Top of line passion

Defined charter and scope of the WG• Consider trends, research in information architectures

• Exploit XML and related technology standards

• Extend into areas outside ownership to define boundaries

• Mentor/Offer competence to others• Establish thought leadership• Develop and enhance analytic skills



Promise and Reality of XML

Promise• Separation of 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 may not be specific to your needs

• Knowledge representation is strongly related to current corporate culture; fixed schemas carry past issues throughout the lifecycle.

Tradeoff• The more useful your markup is to you, the more it will cost you and

the fewer people will share the costs



The result: DITA

First published on developerWorks March 2001

Prototyped internally for a year

Development of internal, external communities for tools, users

Movement toward open standards and open source



What is DITA?What is DITA?



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



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



The core DITA information types – The “IT” in DITA

topic

concept task reference

Provides background information that users need to know.

Provides quick access to facts.Provides procedural details such as step-by-step instructions.

A unit of information which is meaningful when it stands alone.



Types of reuse with DITA

Reuse of Content

Reuse of Design

Reuse of Processes



Reuse of content (principle of topic granularity)Reuse of content (principle of topic granularity)



What is a book?A book as a collection of topics

Part I Part II Part III

Chapter 1 overview

Chapter 2 overview

Chapter 3 overview

Chapter 4 overview

Chapter 5 overview

Chapter 6 overview

Topic A

Topic B

Topic C

Topic A

Topic B

Topic C

Topic A

Topic B

Topic C

Topic A

Topic B

Topic C

Topic A

Topic B

Topic C

Topic A

Topic B

Topic C



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



Topics reused in deliverablesTopics reused in deliverablesTopic 1

Topic 4

Topic 2

Topic 3

ƒ Deliverables select topics from a poolƒ Deliverable 1 uses topics 1 and 4ƒ Deliverable 2 uses topics 2 and 4ƒ Neither deliverable uses topic 3



Working with DITA maps

A DITA map applies context to the topics

Organizes a set of topics in a hierarchy and sequenceDifferent 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 hierarchyProperties 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

Eclipse help

JavaHelp

HTMLHelp

web pages

books



Integrated Instructions for Creating a Web Store Front

Serving the catalogto customers

Creating the database catalog

Managing the system

Designing the system

Messaging notifications

Component Instructions

Integrated solution view: Web Store example

Integrate custom information



Web-browser view / information center view

Task

Concept

Reference

Online View

Multiple Product

Task 1 Task 2 Task 3

Concept 1 Concept 2 Concept 3

Reference 1 Reference 2 Reference 3



Reuse of design (principle of specialization)Reuse of design (principle of specialization)



Reuse of design

General types are rarely enough• Requirements specific to organization or industry

• tasks may span both usage and problem determination

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



Specializing from Topic to Task

Small DTD additions to enforce document structure.

May have no CSS or XSL process changes.

topic

title

prolog

metadata

related-links

body

task

title

prolog

metadata

taskbody

prereq

context

steps

taskxmp

result

postreq

step

cmd, (info | substeps | tutorialinfo | xmp | choices)*, result?

related-links

topic

title

prolog

metadata

related-links

body

task

title

prolog

metadata

taskbody

prereq

context

steps

example

result

postreq

step

cmd, (info | substeps | tutorialinfo | stepxmp| choices|choicetable)*, stepresult?

related-links



From Task to Business Task

Additional structure changes.

businesstask

title

prolog

metadata

related-links

btaskbody

prereq

context

bsteps

example

result

postreq

step

appstep

appdesc

task

title

prolog

metadata

taskbody

prereq

context

steps

taskxmp

result

postreq

step


related-links

task

title

prolog

metadata

taskbody

prereq

context

steps

example

result

postreq

step


related-links



Specializations from Topic

Java APIs C++ APIs

Topic

Concept TaskReference

minitask bctaskmanpages UI help APIs Messages

Java APIs C++ APIs

Topic

Concept TaskReference

minitask bctaskmanpages 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.



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



Reuse of processes (principle of specialization)Reuse of processes (principle of specialization)



Reuse of processes

Base processing is in extensible XSLT

Overrides provide class-like inheritance of processes

• Standard processing can be customized as needed

• New elements can be given specific behaviors

Processes for base elements apply to new specialized elements by default

• Can rely on base processing, but

• Can write new/custom processing if needed



task

title

prolog

metadata

taskbody

prereq

context

steps

taskxmp

result

postreq

step


related-links

task

title

prolog

metadata

taskbody

prereq

context

steps

example

result

postreq

step


related-links

task

title

prolog

metadata

taskbody

prereq

context

steps

taskxmp

result

postreq

step


related-links

task

title

prolog

metadata

taskbody

prereq

context

steps

example

result

postreq

step


related-links

Produce information without “steps”, just numbered list

Produce PDF document with “steps”

Create a wizard to lead user through steps of a task

Automatically performAutomatically validate

Produce information web with “steps”

XSLTDITA TaskPossible Outputs



Specialized processes handle the delta for specialized topic types

Basetopic

Task

Concept

Reference

bcTask

bcReference

Specialization-specific processors

Base processors

Base and delta DTDs Base and delta processors

Specialized processesSpecialized processes



Summary of reuse

Reuse content through topics• Author content as standalone information

• Reuse topics as components

Reuse designs through specialization• Meet requirements specific to your organization

• Keep interoperability with others

Reuse processing• Inherit base and intermediate processes

• Customize new specialization only as needed



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• Customize and update information



DITA and the Open Community

Making the design open - DITA at OASIS• OASIS TC has excellent participation by vendors, consultants, implementers, users

• Conducted a series of briefings for members, interested guests

• TC chartered to draft first specification toward end of summer

• DTDs and schemas in toolkit are the "reference implementation"

• DITA at OASIS http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita

• DITA resources on “OASIS Cover Page” - http://xml.coverpages.org/dita.html

Making the code open• Initially published through IBM developerWorks for mindshare and validation

• Built a community of tool users based on a freely available toolkit

• Will continue to be enhanced as a usable production system and demo of DITA capabilities

• Evaluating priorities for what is needed in the Open Source community

OASIS – Organization for the Advancement of Structured Information Standards



Thank you! Time for questions…



Backup Slides

IBM Corporate User Technology

An Introduction to DITA © 2004 IBM Corporation

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>

Identifier, title, and shortdesc

Properties of the topic

Type-specific content body

Relationships to other topics

IBM Corporate User Technology

An Introduction to DITA © 2004 IBM Corporation

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>

A heading doesn’t have to have a topic

Title and properties can be assigned in the map

A topic can appear multiple times in the hierarchy

The map organizes a set of topics in a hierarchy



DocBook and DITA

DocBook starts with a fairly comprehensive idea of what a book is, and has a sub-setting scheme for selecting specific parts out of that

Provides mature, standard solution for linear texts such as technical books and articles

Good single sourcing, good interoperability, multiple outputs

An element set refined carefully over a decade, recognition as a standard, and an active open-source community.

Good for users who want to author in the book model

DITA starts with a very constrained idea of what a chunk is, and then has a specialization scheme for describing more kinds of content and constraints

Granularity makes repurposing much easier; plugged into user interfaces, stored in a database and rendered individually on demand, and so on.

Specialization brings the benefits of object-oriented design to information typing

DITA markup encourages the author to focus on reuse

Documents

IBM Corporate User Technologies January 10, 2005 © 2004 IBM Corporation An Introduction to Darwin Information Typing Architecture: DITA Don Day, Chair,