Scenariobased information development with DITA Michael Priestley IBM

Business Unit or Product Name Agenda § Assumptions – What we want our information to be – What we want out of a process § Scenario-based information development 1. Develop understanding 2. Develop architecture 3. Develop content 4. Rinse and repeat 2 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name Our information should be: § Audience-focused § Task-oriented § Accurate § Easy to read and navigate § Support new users and experienced users § Easy to give feedback on 3 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name Our information 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 4 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name An end-to-end flow 5 Scenario-based information development with DITA

Business Unit or Product Name 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 6 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name 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 7 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name Step 1. Defining your audience 1. Define roles: who they “should” be 2. Research: who they actually are 3. Define responsibilities 4. Define skills: what they need to know to fulfill those responsibilities 8 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name Step 1 cont. Identifying roles and goals § Identify roles and goals for the product UML and UEUML are good modeling choices. Information architect should be involved with this activity. 9 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name Step 2. Creating personas and scenarios for the roles and goals § DITA documents are an appropriate media/format § Information architect should be involved in this activity § John sells an old toy: Prepares the toy and takes pictures using his digital camera Registers at the auction site and posts it under the category "vintage collectables" Sets a reserve bid of $10 § Bob buys a vintage collectable: etc. 10 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name What makes a good scenario? § Realistic (not just made-up) § Useful (not trivial, not idiosyncratic) § Complete (don't gloss over parts you don't understand) § Goal-oriented (not just exploration, describe achievement) § End-to-end (support the goal even outside of the product) § Specific (don't try to be universal, or comprehensive) § Coordinated (ties together with other scenarios where possible, part of the big picture) § Documented (don't just invent and throw away) § Accurate (you can make guesses, but must validate them) 11 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name Step 3. Developing samples and tutorials § DITA topics are an appropriate media for documenting samples; DITA mixed-type documents are appropriate media for tutorials § Sample product: A vintage toy § Tutorial: Placing a bid on a vintage toy § Both the information architect and information developer may be involved in this activity. § Smaller/more focused tutorials and samples may not require the involvement of information architects § Identify what skills the tutorials build, and map to the skills required for each role. 12 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name Review: 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 4. …And start testing with users 13 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name 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 14 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name 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. 15 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name 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. 16 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name 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. 17 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name 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. 18 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

Business Unit or Product Name 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) 19 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name 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 20 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name Review: The end-to-end flow 21 Scenario-based information development with

Business Unit or Product Name 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 22 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name 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 23 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name 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 24 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name 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 25 Scenario-based information development with DITA © 2005 IBM Corporation

Business Unit or Product Name More about DITA § See DITA Fact Sheet in conference proceedings. § DITA articles: http: //www. xml. coverpages. org/dita. html § OASIS DITA Technical Committee: http: //www. oasis-open. org/committees/dita § DITA toolkit: http: //dita-ot. sourceforge. net 26 Scenario-based information development with DITA © 2005 IBM Corporation