interoperable extensibility through dita topic and domain types

IBM User Technologies

| April 2005 | © 2005 IBM Corporation

Interoperable ExtensibilityThrough DITA Topic and Domain Types

Erik HennumIBM DITA Domains Architect


Extensibility Through DITA Topic and Domain Types © 2005 IBM Corporation2

The discussion aheadThe discussion ahead

What is DITA? – Why was DITA developed?

What is specialization? – How do you extend DITA?

What areTopic types?

Domain types?

Maps and map domains?



What is DITA?What is DITA?



History of Markup

1970s:ISIL

1980s:BookMaster

IPF

1990s:SGML, HTML

2000+XML-based semantics

Need for Change

Printed Books

Limited reuseSingle purpose

Printed and onlineBooks, online help

Monolithic Book-Centered DTD

Shorter cyclesFewer people,

Decreasing learning curves, Faster, better, cheaper

Components,Multiplatform,

Integrated systems

Web-deployed products Partner and OEM use of

information

Online information,Webs, printable &

Printed books

Information Architecture



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

Multiple formats



Core design principles of DITA

Topic orientation• Each content object covers one subject for a specific purpose

Topic granularity• Content objects are assembled into information sets

Strong typing• Types enforce structures specific to the content semantics

Type specialization• Types extend more basic types to model new kinds of information

Common base class• The top-level generic type provides interoperability and fallback for all topics



What is DITA specialization?What is DITA specialization?



The motivation for specialization

The realization• Generic XML solutions are not specific to your needs

• Knowledge representation is strongly related to industry, community, and organization culture

The existing tradeoff• The more useful your XML markup is to you, the more it will cost you

and the fewer people will share the costs



Specializing a topic type

The specialized topic type for procedural instructions works toGuide the writerEnforce the structureDeclare the semanticsIn short, make the content easier to understand, validate, and process

General topic<topic id="installstorage"> <title>Installing a hard drive</title> <body> <ol> <li><ph>Unscrew the cover.</ph> <itemgroup>The drive bay...</itemgroup> </li> <li><ph>Insert the drive...</ph> <itemgroup>If you feel...</itemgroup> </step> </ol> </body></topic>

Specialized task<task id="installstorage"> <title>Installing a hard drive</title> <taskbody> <steps> <step><cmd>Unscrew the cover.</cmd> <stepresult>The drive...</stepresult> </step> <step><cmd>Insert the drive...</cmd> <info>If you feel resistance...</info> </step> </steps> </taskbody></task>



Specialization rules

Design constraint – extension by restrictionThe content model must be a specialized subset of the base modelAs a result, every instance of the derived model is valid for the base modelA good fit for discourse because text tends toward loose content models

Declare the specialization ancestry with the class attribute in the schemaDTD: <!ATTLIST steps class CDATA "- topic/ol task/steps ">XML Schema: <xs:attribute ref="class" default="- topic/ol task/steps "/>

The ol element in the topic module is the base of the steps element in the task module

Process by matching the element type in the class attributeXSLT idiom: <xsl:template match="*[contains(@class,' topic/ol ')]">

Specializations can rely on the base processing or override.



Implementing a specialized <steps> element

The class attribute identifies the module and type ancestry

Base processing applies by default

The specialization can override base processing

topic design module:<!ELEMENT ol (%li;)+>...<!ATTLIST ol class CDATA "- topic/ol "><!ATTLIST li class CDATA "- topic/li ">

task design module:<!ELEMENT steps (%step;)+>...<!ATTLIST steps class CDATA "- topic/ol task/steps "><!ATTLIST step class CDATA "- topic/li task/step ">

topic processing module:<xsl:template match="*[contains(@class,' topic/ol ')]"> ...

task processing module:<xsl:template match="*[contains(@class,' task/steps ')]"> ...

Every element has an architectural class attribute



Generalizing to the base type (casting)

An automated process can preserve the content but convert from specialized to general markup:

To send content to someone who doesn’t have your specialized markup

To retire specialized markup but keep the content

To provide content to a tool that understands only element names and not the DITA class attribute

Tutorial

my types

MaintenanceProcedure

your types

Task

our types



What is a DITA topic type?What is a DITA topic type?



Specialization hierarchy for topic types

Topic

Concept Task

Tutorial

Java APIC++ API

Command Message

Reference

API

The topic type provides the coarse structure and semantics for content

Eventannouncement

Insuranceclaim form

Use casespecification

or

or

or. . .



Parts of a DITA topic

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

</task>

Identifier and labels

Processable properties

Content structure for the topic type



A hybrid topic with both data and discourse content

<enote id="note1">

<subject>How to compose an eNote</subject>

<notedetail>

<noteheader>

<From>

<recipient href="[email protected]"/>

</From>

<To>

<recipient href="[email protected]"/>

</To>

...

</noteheader>

<notebody>

<p>To compose an eNote, you ...</p>

...

</notebody>

</notedetail>

</enote>

Specialized data

Discourse



What is a DITA vocabulary domain?What is a DITA vocabulary domain?



Specialization of vocabulary domains

Use a domain in many topic typesDefines metadata properties, kinds of names, or text structure for a subject area

Fine-grained structure and semantics

DITA core domainsprogramming: apiname, codeph, codeblock, …

software: cmdname, filepath, varname, …

user interface: wintitle, uicontrol, …

highlighted phrases: b, i, u, sup, sub, …

Create new domains for subject areasTelco, Semiconductor, Financial, Insurance, Retail, Legal, Life Sciences, …

Task topic typeSoftware domain

UI domain

Programming domain

Highlighting domain

Domains as blades for topic typesDomain inheritance

UI domain

Web UI domain

topic elements



Pluggability of topic and domain modules

To create a document type, you plug in specialization modules• For financial services software, you might include

• The task type• The UI domain• A new domain that you created for the vocabulary of the financial industry• The highlighting domain – if you are a pragmatist

Task topic type

Financial domain

UI domain

Highlighting domain

?



Example of some DITA domain phrases

<task id="amortizingloan">

<title>Amortizing the loan</title>

...

<taskbody>

<steps>

<step><cmd>Choose the Amortizer menu item</cmd>

<stepresult>The <wintitle>Amortizer</wintitle>

window displays.</stepresult>

</step>

<step><cmd>Enter the <loanfactor>term</loanfactor>.</cmd>

<info>You <b>must</b> choose one of the options.</info>

</step>

</steps>

</taskbody>

</task>

UI domain

Financial domain (possible future)

Highlighting domain



What is a DITA map?What is a DITA map?



Topics reused in information setsTopics reused in information sets

Topic 1

Topic 4

Topic 2

Topic 3

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



Working with DITA maps

A DITA map applies context to a set of topicsAssembles an information set for a purpose such as a deliverable

Supports reuse of topics in different structures in multiple information sets

Sets the contextual properties of topicsTitles and metadata

A topic can be advanced in one set and basic in another

Specifies relationships between the topics

Eclipse help

JavaHelp

HTMLHelp

web pages

books

topics map deliverables



Relationships between topics managed in a map

Hierarchical structuresBook nesting or web or help navigation – but also parts explosion, …

Group structuresRelated links – but also any distributed or sequential association

Tabular structuresRelated links – but also any matrixed association between topics

hierarchy group table



Examples of topic references in a DITA map

<map title="Enterprise web management"> <topicref href="installoverview.dita" audience="admin"> <topicref href="installdb.dita"> <topicref href="closeprograms.dita"/> <topicref href="runsetup.dita"/> ...

<topicgroup collection-type="family"> <topicref href="installdb.dita"/> <topicref href="configuredb.dita"/> ...

<reltable> <relrow> <relcell> <topicref href="installdb.dita"/> </relcell> <relcell> <topicref href="dbconcepts.dita"/> </relcell> ...</map>

Contextual property

Group relationships

Hierarchical relationships

Tabular relationships



Example of possible map domains

Pluggable vocabularies for maps

Specialized references to topicsSpecify the topic role within a set of topics

Specify the topic type for validation

Specialized group or tabular structuresThe semantics of the relationship between the referenced topics

<map> ... <howto href="dita-mapdomains.xml"> <taskref href="implementDomain.xml"/> ...

<annotationRow> <publicCell> <topicref href="installdb.dita"/> </publicCell> <serviceCell> <topicref href="installfix.dita"/> </serviceCell> ...</map>

Role for referenced topic

Semantic table structure

Type of referenced topic



The DITA vision: a platform for collaboration

Retail

Medical Legal

Marketing

Technical

Core

Content markup that’s specific to the subject area

Marketing event announcements, Development functional specifications, orReal estate appraisal forms

Shared markup modulesAcross industry segments or communities

and between partners

Local markup for the organizationAgree on the shared basics, diverge on the

local idiosyncrasies

Install the specialization modules, assemble the document types, and go



Summary of business value

Faster time to value– create solution offering across industry stacks or within your business

with different components

Increased reuse– of content by referencing topics in many map contexts

– of designs by providing only the specialized delta on the general base

– of processing by overriding the base only where needed

Investment protection– because of automated fallback to more general markup



DITA and the Open Community

The DITA Standard at OASIS• Contributed in 2004

• DITA 1.0 specification – Committee Recommendation

• DITA Technical Committee includes:

XML tool vendors (Arbortext, Blast Radius, Idiom, Rascal, Syntext) Consultants (Comtech, Innodata, Mulberrytech) Companies (BMC, Boeing, IBM, Intel, Lucent, Nokia, Oracle, Sun)Education and government (National Library of Medicine,

US Department of Defense)

The DITA Open Toolkit at SourceForge• Successor to public toolkit published through IBM DeveloperWorks

• Reference implementation – usable for production, ongoing enhancement

• Other community-contributed utilities

• Community specialization modules

• Samples and demos of DITA capabilities



Where next?

Learn more about DITA• OASIS – http://www.oasis-open.org/committees/dita

• Cover page – http://xml.coverpages.org/dita.html

Where do we take DITA together?• Join the dialog on the DITA forum –

http://groups.yahoo.com/group/dita-users/

Download the DITA Open Toolkit• http://sourceforge.net/projects/dita-ot/



BackupBackup



DITA defined

Darwin: DITA utilizes principles of inheritance for specialization

Information Typing: DITA was 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



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

interoperable extensibility through dita topic and domain types

Documents