An Introduction to Darwin Information Typing Architecture: DITA

IBM Corporate User Technologies

| February 2004 | © 2004 IBM Corporation

An Introduction to Darwin Information Typing Architecture: DITA


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



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



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

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• Establish thought leadership

• Develop and enhance analytic skills



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



DITA designed to address trade-offsDITA designed to address trade-offs

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 topic 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.



DITA and reuseDITA and reuse



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



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 contentCan reuse the same topic with different collections of topicsCan 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 metadataChange the title relative to the parent topicMetadata can identify a topic as advanced for one deliverable and basic for another

Eclipse helpJavaHelpHTMLHelpweb pages

books



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



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

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

related-links

task

title

prolog

metadata

taskbody

prereq

context

steps

example

result

postreq

step

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

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

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



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



SummarySummary



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



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



Backup Slides



Epic Editor with DITA Maps

Manage hierarchy

Create new & edit

Preview HTML & PDF

Check out



Epic Editor with DITA Topics

Content edit

Common elements

Indexing, linking helpers

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

An Introduction to Darwin Information Typing Architecture: DITA

Documents

Transcript of An Introduction to Darwin Information Typing Architecture: DITA