© 2005 IBM Corporation
Scenario-based information development with DITA
Michael Priestley, IBM
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation2
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation3
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation4
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation5
An end-to-end flow
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation6
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 samplesPhase 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 schemePhase 3 - Develop content
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation7
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation8
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation9
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.
Buyer
Buying items
Seller
Selling items
Product
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation10
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.
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation11
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)
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation12
Step 3. Developing samples and tutorials
DITA topics are an appropriate media for documenting samples; DITA mixed-type documents are appropriate media for tutorials
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.
Sample product: A vintage toy
Tutorial:Placing a bid on a vintage toy
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation13
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation14
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation15
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
Information architect determines high-level task flow
Information developers may own parts of task flow that are specific to a component they own.
1. Buying items1. 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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation16
Step 2. Identifying supporting materials
DITA maps (relationship tables) are appropriate media. Relationship tables should be stored with the component that owns the tasks they support.
Information architects develop 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.
Categories Browsing categories
Item properties
Sellers Asking sellers questions
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation17
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 overall organization, and work with information developers to implement.
ItemsQuality of items
Categories of items Shipping prices
Post
Courier
International
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation18
Step 4. Integrating topics into a single navigation scheme
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.
1. Buying items 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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation19
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)
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation20
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation21
Review: The end-to-end flow
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation22
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation23
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation24
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation25
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
Business Unit or Product Name
Scenario-based information development with DITA © 2005 IBM Corporation26
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