introduction to information modeling with dita

Alan HouserPrincipal Consultant and Trainer

Tel: 412.363.3481arh@groupwellesley.comwww.groupwellesley.com

Introduction to information modeling with DITA

Group Wellesley, Inc.

What you will learn

• Overview of DITA architecture

• Overview and structure of DITA information types

• Purpose and structure DITA map files

• Information modeling from a DITA perspective

• Techniques for rapid prototyping DITA deliverables

What’s different about technical publishing today?

• Time-to-market pressures

• Increasing activity in international markets

• Increasing needs/opportunities for information reuse

• Multiple products, multiple audiences, multiple deliverables

• Increasing needs/opportunities for content management

What’s different for our documentation departments?

Judging documentation departments and technical communicators:

• Old way: Volume of output

• Word count, page count, topic count

• "A fat manual is a good manual."

• Encourage writers to document "everything."

But...

Content must be:

• Created

• Updated

• Managed

• Localized

• Published

This translates to $$$ that can be saved.

A different approach

• Provide task-oriented documentation.

• Provide navigation and accessibility mechanisms.

• Minimize amount of content provided to support your product or service.

• Maximize usability.

Overview of DITA design

• Roots of DITA: minimalist approach

How to get there

• Document tasks that users must accomplish.

• Document concepts that provide background for accomplishing tasks.

• Provide reference information that users need to accomplish tasks.

• Provide navigation and structure to support users in finding information.

DITA in Context

• Developed by IBM corporation as a successor/replacement for IBMIDDoc (a "book-centric" information model).

• Donated by IBM to OASIS (Organization for the Advancement of Structured Information Standards).

• DITA 1.0 finalized by DITA Technical Committee February 2005, formally approved by OASIS June 2005.

• DITA 1.1 formally approved 1 August 2007.

What is DITA?

Darwin Information Typing Architecture

• An architecture that supports authoring, managing, and publishing topic-oriented content.

Why DITA?

• Companies are looking for publishing solutions that facilitate information re-use, reduce time-to-market, improve management and maintainability, and provide the capability to deliver highly usable technical content.

DITA architecture

• Topics – typed, reusable units of information

• Specialization mechanism to create new topic types

• Maps define topic collections

• Content reuse at topic and fragment level

• Metadata-based content filtering

• Basic DITA information unit

• Should be stand-alone, usable out of context

• No formal restriction on topic length

• Generic "topic" type

• Specialized topic types: task, concept, reference

DITA Topic

Structure of a DITA Topic

<topic> <title/> <titlealts/> <shortdesc/> <prolog/> <body/> <related-links/></topic>

Structure of a DITA Concept Type

<concept> <title/> <titlealts/> <shortdesc/> <prolog/> <conbody/> <related-links/></concept>

Structure of a DITA Reference Type

<reference> <title/> <titlealts/> <shortdesc/> <prolog/> <refbody/> <related-links/></reference>

Structure of a DITA Task

<task> <title/> <titlealts/> <shortdesc/> <prolog/> <taskbody/> <related-links/></task>

Structure of a DITA Task (continued)

<taskbody> <prereq/> <context/> <steps> <step><cmd> </cmd></step> <step><cmd> </cmd></step> … </steps> <result/> <example/> <postreq/></taskbody>

• Generate set of tasks

Workshop Exercise

• Define topic sequences, hierarchies, groups

• Define topic sets and structure for publishing

• Define topic sets for project management and authoring responsibility

• Define navigation structures

• Augment and override topic-level metadata

DITA Maps

<map title = "Using your Acme Cell Phone"> <topicref href="answer_call.xml"/> <topicref href="attach_battery.xml"/> <topicref href="change_case.xml"/> <topicref href="charge_battery.xml"/></map>

A basic DITA map file

Expressing topic hierarchies

• <topicref> elements can be nested to express topic hierarchies in navigation and output:

<topicref href = "maintaining_battery"> <topicref href = "charge_battery.xml"/> <topicref href = "attach_battery.xml"/> <topicref href = "detach_battery.xml"/> <topicref href = "replace_battery.xml"/></topicref>

Expressing headings within a map

• Use <topichead> to provide title for a group of <topicref> elements. Title is rendered in output.

<topichead navtitle="Maintaining your battery"> <topicref href="attach_battery.xml"/>

<topicref href="charge_battery.xml"/> <topicref href="detach_battery.xml"/>

<topicref href="replace_battery.xml"/></topichead>

Overriding topic headings within a map

• Use navtitle attribute to override topic titles for navigation. Must also set locktitle attribute to "yes".

<topichead navtitle="Battery"> <topicref href="charge_battery.xml"

navtitle="Charge" locktitle="yes"/> <topicref href="attach_battery.xml"

navtitle="Attach" locktitle="yes"/> <topicref href="detach_battery.xml"

navtitle="Detach" locktitle="yes"/></topichead>

Overriding topic-level metadata

• DITA 1.0 provides 4 attributes to support topic filtering: audience, platform, product, otherprops. These are typically set in the topic file, but can be set or overridden in the map file.

<topic audience="administrator"> … </topic>

<topicref href="troubleshooting.xml" audience="user" />

• DITA 1.1 allows you to specialize the props attribute to provide your own attribute "labels".

Expressing related topics

• Use <reltable> element to express and maintain related topics outside the topic bodies.

• Expresses table structure through <relrow> and <relcell> elements.

• Typically a two or three-column table (can be single column).

• By default, topics in separate cells in row are expressed as related links. Topics within a cell are not unless explicitly labelled.

Expressing related topics

<reltable><relrow> <relcell collection-type = "family"> <topicref href = "charge_battery.xml"/> <topicref href = "attach_battery.xml"/> <topicref href = "detach_battery.xml"/> <topicref href = "replace_battery.xml"/> </relcell></relrow></reltable>

Controlling content for print/PDF output

• Include or exclude topics from print or PDF output using "print" attribute.

<topicref href="preface.xml" print="printonly" />

<topicref href="using_help.xml" print="no" />

• Exclude topics from toc using "toc" attribute.

<topicref href="copyright.xml" toc="no" />

Sounds like a good idea. Let’s go!

Conventional approach to DITA migration

• Analyze legacy documents

• "Chunk" legacy content

• Assign topic types

• Rewrite content as necessary

• Convert content to markup

• Organize using DITA map files

A better approach

Task-based approach

• Perform task analysis

• Determine supporting concept and reference topics

• Create organizing structure: sequences, hierarchies, groups

• Pull topics from legacy documentation as needed

• Write to fill the holes

• Throw the rest (of your legacy content) away

Task analysis methodologies

• GOMS (Goals, Operators, Methods, Selection) and similar methodologies (Card, Moran, Newell)

• Card sorting

• Post-it notes

• Mind-mapping applications

IBM Task Modeler

A GUI-based tool for performing task analysis and generating DITA maps.

Workshop Exercise

Using the IBM Task Modeler with DITA

•Task analysis – record with IBM Task Modeler

•Create DITA map and stub files

•Run through DITA Open Toolkit

•Generate rapid-prototype help system!

Resources

• DITA Architecture Specification and Language Reference

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

• DITA Open Toolkit

http://sourceforge.net/projects/dita-ot/

• IBM Task Modeler

http://www.alphaworks.ibm.com/tech/taskmodeler

Resources (continued)

• OASIS DITA Web resourceshttp://dita.xml.org

• Minimalism Beyond the Nurnberg Funnel, edited by John Carroll, MIT Press, 1998

Contact Us!

We hope you enjoyed this workshop. Please feel free to contact us:

Alan Houserarh@groupwellesley.com

Group Wellesley, Inc.933 Wellesley RoadPittsburgh, PA 15206USA412-363-3481www.groupwellesley.com