© 2005 IBM Corporation Presentation subtitle: 20pt Arial Regular, teal R045 | G182 | B179 Recommended maximum length: 2 lines Confidentiality/date line:

© 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



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



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



An end-to-end flow



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



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



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



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



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.



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)



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



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



Phase 2 - Developing architecture




4. Integrate topics into navigation scheme



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



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



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



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



Review: Phase 2 - Developing architecture




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)



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



Review: The end-to-end flow



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



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



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



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



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

Documents

© 2005 IBM Corporation Presentation subtitle: 20pt Arial Regular, teal R045 | G182 | B179 Recommended maximum length: 2 lines Confidentiality/date line: