# Presentation: 039648

## An Introduction to Darwin Information Typing Architecture: DITA 

- Don Day, Chair, OASIS DITA Technical Committee
- IBM Lead DITA Architect
- Presented to OASIS Business Centric Methodology Technical Committee

## Agenda

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

## History of markup in IBM

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

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

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

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

## What is a book?

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

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

- Eclipse help
- JavaHelp
- HTMLHelp
- web pages
- books

## Integrated solution view: Web Store example

**Integrate custom **
**information**

## Web-browser view / information center view

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

## Specializations from Topic

- 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

- 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

## Produce information without “steps”, just numbered list

**Produce information without “steps”, just numbered list**

**Produce PDF document with “steps”**

**Create a wizard to lead user through steps of a task**

**Automatically perform**
**Automatically validate**

**Produce information web with “steps”**

**XSLT**

**DITA Task**

**Possible Outputs**

**Notes:**
Processors (XSLT) can use the underlying semantics of information – here “steps”.  The process can support the output of the word “step” or output numbered steps – or anything n between.  More importantly, we can create wizards or potentially automate the steps.  Most important, the process does not have to support the semantics – this is good and bad – in a specialization, for consistency you might not want to support the rich semantics on output if you are combining information from multiple sources – some with and some without specializations.

## Specialized processes

- Base
- topic

- Task

- Concept

- Reference

- bcTask

- bcReference

- Specialization-specific processors

- Base processors

- Base and delta DTDs

- Base and delta processors

## 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](http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita)__[=](http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita)__[dita](http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita)_
- DITA resources on “OASIS Cover Page” - _[http://xml.coverpages.org/dita.html](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

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

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