Alan HouserPrincipal Consultant and Trainer
Tel: [email protected]
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 [email protected]
Group Wellesley, Inc.933 Wellesley RoadPittsburgh, PA 15206USA412-363-3481www.groupwellesley.com
