IBM User Technologies Using DITA for information architecture

IBM Information Development Agenda § DITA background – What is DITA § Assumptions – What we want our information to be – What we want out of a process § Scenario-based information development 1. Goals and roles 2. Scenarios, samples, and tutorials 3. Task flows, relationships, conceptual groupings; navigation 4. Content development 2 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development DITA background § DITA defined § DITA maps § DITA specialization

IBM Information Development 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 4 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development DITA maps: separating content from context Eclipse help Java. Help HTMLHelp web pages books 5 § A DITA map provides context for topics § Organizes a set of topics into hierarchies, tables, groups, sequences etc. Different organization for different deliverables — not just different formats 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 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development DITA specialization: better semantics at lower cost topic task title prolog metadata body taskbody related-links Small DTD additions to enforce document structure. May have no CSS or XSL process changes. 6 Scenario-based information development with DITA prereq result context taskxmp example steps postreq step cmd, (info | substeps | tutorialinfo | stepxmp | |xmp choices|choicetable)*, | choices)*, result? stepresult? © 2005 IBM Corporation

IBM Information Development DITA at IBM § In use across IBM § 100 s of projects § 100, 000 s of topics § Some new, most converted from SGML or HTML § Translated into over 40 languages 7 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development DITA at OASIS § DITA architecture (including base topic types) contributed to OASIS in 2004 § DITA 1. 0 specification (Committee Draft) out under public review § DITA open-source toolkit at dita-ot. sourceforge. net § OASIS 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) § Organizations (National Library of Medicine, US Department of Defense) 8 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Assumptions § Information needs § Process needs 9 Scenario-based information development

IBM Information Development Our information needs to be: § Audience-focused § Task-oriented § Accurate § Easy to read and navigate § Support new users and experienced users § Easy to give feedback on 10 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Therefore our development process needs to be: § Focused on user goals § Focused on end-to-end support of the users’ tasks § Deliver content on time § Provide verifiable results § Allow for mid-course corrections, and help authors manage changing requirements § Allow for user involvement/feedback at every stage, not just the end 11 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development An end-to-end flow 12 Scenario-based information development with DITA © 2005

IBM Information Development Another view Phase 1 - Develop understanding 1. Audience analysis 2. Model roles and goals 3. Create personas and document scenarios 4. Develop first-draft tutorials and samples Phase 2 - Develop architecture 1. Define task flow, overall and per role 2. Identify supporting materials 3. Organize supporting materials 4. Integrate supporting materials into navigation scheme Phase 3 - Develop content 13 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Phase 1 - Developing understanding 1. Define your audience, and identify roles and goals 2. Make roles concrete with personas, make goals concrete with scenarios 3. Adapt key parts of scenarios for tutorials and samples 14 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Phase 2 - Developing architecture 1. Define task flow, overall and per role 2. Identify supporting materials 3. Organize supporting materials 4. Integrate topics into navigation scheme 15 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Step 1 - Defining task flows § DITA maps are appropriate media for expressing hierarchies with sequences; chunk the map based on who will own each part, and based on role divisions. But also capture end-to-end flow, to show interaction among roles. § Use HTA (hierarchical task analysis) with scenarios as input 1. Buying items 1. Finding items § Browsing by category § Searching for items 2. Evaluating items § Assessing quality § Asking the seller questions § Comparing prices 3. Placing bids 4. Paying for items § Information architect determines high-level task flow § Information developers may own parts of task flow that are specific to a component they own. 16 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Step 2 - Identifying supporting materials § DITA maps (relationship tables) are Categories appropriate media. Relationship tables should be stored with the component that owns the tasks they Sellers support. § Information architects develop Browsing Item categories properties Asking sellers questions overall organization, and work with information developers to identify required supporting material for each task, coordinating to avoid ambiguity in titles and redundancy in content. 17 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Step 3 - Organizing supporting materials § DITA maps (hierarchies and groups) are appropriate media. Conceptual groupings and reference categories may uncover the need for new topics, which are fed back into the relationship table. § Information architects develop § Items Quality of items Categories of items § Shipping prices Post Courier International overall organization, and work with information developers to implement. 18 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Step 4 - Integrating topics into a single navigation scheme 1. Buying items § DITA maps (hierarchies) are appropriate media. One map per reusable user goal or reference category. Use linking attribute to prevent included concepts from affecting task-oriented links. § Integration may be done in different ways, or not at all – for example, tutorials and samples could have their own galleries, and have only summary topics in the navigation. § Information architects own the overall navigation; information developers may be responsible for parts of navigation that are within the boundaries of components they own. 19 Scenario-based information development with DITA § Tutorials and samples for buying items § Sample: A vintage toy § Tutorial: Buying a vintage toy – About items 1. Finding items § Categories § Browsing by category § Searching for items 2. Evaluating items § Sellers and item quality § Sellers § Quality of items § Assessing quality § Asking the seller questions § Comparing prices 3. Placing bids 4. Paying for items § Shipping prices Post Courier International © 2005 IBM Corporation

IBM Information Development Review: Phase 2 - Developing architecture 1. Define task flow, overall and per role 2. Identify supporting materials 3. Organize supporting materials 4. Integrate topics into navigation scheme 5. …Build a prototype information system and start testing with users. Feed results back into previous phase, as well as forward into next. § Internal prototypes can include links between scenarios and topics for ease of change tracking (add a scenarios column to the reltable) 20 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Phase 3 - Developing content § DITA topics (concept, task, and reference topics, or other specialized topic types) are appropriate media. § Information architects and information developers develop the content for the portions of task flows that they own § Avoid links in content, which make topics less reusable. Manage links using maps instead, wherever possible. § Test results, and embed feedback mechanisms 21 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Review: The end-to-end flow 22 Scenario-based information development with DITA ©

IBM Information Development Review results: Our information should be: § Audience-focused – start with audiences, include audience definitions/awareness in every stage § Task-oriented – drive all content development and navigation from task flows § Accurate – test early and often § Easy to read and navigate – reflects user tasks both in content and organization § Support new users and experienced users – same understanding and language in tutorials and in help system § Easy to give feedback on – make tutorials and prototypes available early, embed feedback mechanisms 23 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Review results: Our information development process needs to be: § Focused on user goals – First in development priority, first in navigation § Focused on end-to-end support of the users’ tasks – Task flows used for both development and navigation § Deliver content on time – Tutorials and samples developed first, can be used by Alpha or Beta customers § Provide verifiable results – Tutorials, prototypes, and content are testable § Allow for mid-course corrections, and help authors manage changing requirements – Separation of architecture artifacts (maps) from content artifacts (topics) allows faster, simpler changes at either level § Allow for user involvement/feedback at every stage, not just the end – Feedback opportunities at each stage 24 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Summary 1. User roles and goals drive scenarios 2. Scenarios drive task flows and supporting material 3. Task flows drive content § Testable at each step: tutorials, prototypes, Betas § Result: user focused, 25 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Actual results § Focus on tutorials and samples in early development stages § Focus on scenarios and task analysis § Emerging use of personas, role definitions § Frequent user testing = Dramatic improvement in customer satisfaction 26 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development More about DITA § DITA articles: http: //xml. coverpages. org/dita. html § OASIS DITA Technical Committee: http: //www. oasis-open. org/committees/dita § DITA toolkit: http: //dita-ot. sourceforge. net 27 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development Backup 28 Scenario-based information development with DITA © 2005 IBM Corporation

IBM Information Development DITA map examples § Task flow § Relationship table § Concept hierarchy § Reference categories § Integrated navigation § Built output 29 Scenario-based information development with DITA © 2005 IBM Corporation