Embed Size (px)
DESCRIPTION
Presented at DocTrain East 2007 Conference by Alan Houser, Group Wellesley -- Through effective task analysis and information modeling, organizations can maximize the usability of their technical documentation while minimizing the required development and maintenance effort. During this interactive workshop, students will learn the principles of minimalist documentation, how to perform an effective task and topic analysis, approaches to migrating legacy documentation to DITA or other information models, and methods for mapping content to pre-defined information types. We will also use software tools to assist in performing topic analysis. While this workshop will use DITA information models as examples, the workshop will provide value for anybody who needs to move to a structured authoring environment and improve the usability and maintainability of their technical documentation.In many organizations, writers are judged by the volume of content that they produce. The larger the manual or help system, the more effective the writer. A fatter manual is considered to be a better manual.From the users perspective, however, fatter does not mean better. There is no positive correlation between page or topic count and usability. Large documentation sets may be intimidating and are likely to present usability issues. Furthermore, higher page or topic counts mean higher maintenance, translation, and production costs.The minimalist documentation strategy provides a way to design and deliver highly usable documentation while minimizing the amount of content that must be developed, maintained, and produced to support a product or service. The increasingly-popular DITA information architecture is based on the concepts of minimalist documentation.During this workshop, we will learn the principles of minimalist documentation, and how minimalist documentation strategies meet both user needs and business needs. We will learn how to design minimalist documentation using the DITA information architecture. We will interactively experience the important prerequisite of task and topic analysis for creating well-designed, highly usable minimalist documentation sets.We will also demonstrate the use of software tools to support topic analysis. In an interactive session, we will use the IBM Task Modeler to develop a task analysis for a product or service. The instructor will demonstrate how to use the IBM Task Modeler to automatically generate DITA map files and prototype DITA-based output.
Citation preview
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
