november 2005 © 2005 ibm corporation presentation subtitle: 20pt arial regular, teal r045 | g182 |...

November 2005 © 2005 IBM Corporation

IBM User Technologies

Information architecture using DITA maps

Michael PriestleyIBM®


Information architecture using DITA maps © 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



Understand, then model, then author

First understand your audience and their tasks, using audience analysis, task analysis, and scenarios

Then define the topics you will need for the subject and audience

Finally, create the topics

And expose your assumptions, so your readers can give you intelligent feedback



Iterative information development

Information development

Modeling

Authoring

UnderstandingUnderstand your user and his goals.

Define the outline of information and relationships between areas of information

Develop topic content and define chunks for re-use.



Steps for each phase

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 – Understanding the user

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



Why tutorials and samples so early?

Tutorials and samples flesh out a scenario and make it real and testable

Once you have your tutorials and samples, you can send them out for review, or even release them in a beta version of the product

This means you're writing tasks (in tutorials) and developing samples even before you start defining the taskflow

And it means you're getting feedback on your assumptions before you've developed anything except "Getting started" information

By developing information in the order your users need it, you get feedback when you need it.

By doing the hard stuff first, you make sure it gets done – and you reduce risk for the whole project



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



Phase 1: Demonstration

Documenting a role and a goal with DITA topics

Documenting a scenario with nested topics

Authoring a tutorial with concepts and tasks



Phase 1 Feedback

Test the tutorials with users

Find out what roles and goals have been mismatched

Correct assumptions early



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



List and organize scenario steps into taskflows

Building a model of your users’ tasks:

What are the tasks?

What sequence do they get performed in?

What are the high-level tasks? What are low-level tasks?



Task flow demonstration

Develop a task flow in a DITA map

Create stub tasks based on the task flow

Identify sequences



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



Mapping concepts and reference information

Task-oriented information development:Starting from your tasks:

1. Identify the concepts that support them.

2. Identify the reference information that supports the tasks and concepts.

3. Map tasks to their supporting topics (concept and reference).



Defining relationships in a table

Identify concepts and reference information that support a task

By default, topics defined in one column link to the topics defined in other columns.

Information within a cell is not related unless you set the cell’s collection-type to “family”

Use a separate topicgroup or reltable definition to link together topics that are in the same column/information type.



Relationship table demonstration

Create a relationship table in a DITA map

Identify supporting concepts and reference topics



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



Organize the concepts into a concept hierarchy

Use the concept hierarchy to explain the big picture:– Divide large concepts into parts and examples.

– Organize them into higher-level and lower-level.

– Include user roles in the hierarchy, show how roles relate to each other.

Allow linking between higher-level and lower-level concepts Allow linking between closely related sibling concepts (for

example two competing implementation strategies) Document roles and responsibilities for the user here



Conceptual hierarchy demonstration

Organize concepts into a hierarchy

Identify missing higher-level concepts

Rework relationship table



Prioritize and organize reference information

Use overview topics to create summaries:– Create categories to add value.

– Derive categories from the product/UI, where appropriate.

– Incorporate categories back into your linking models to support high-level tasks.

– When all else fails, alphabetize.

Spend more time on reference topics that are heavily referenced in your model, or are complex/hard to understand



Reference category demonstration

Organize reference topics into categories

Add categories to relationship table



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



Integrate the concept and reference topics into the task hierarchy

Add concepts to support reading flow without breaking task flow:Add high-level concepts as children of high-level tasks.

Add low-level concepts right before their low-level tasks.

Include them for navigation (reading sequence).

Exclude them from linking (supporting relationships are already modeled).

Add reference topics for ease of retrievalReference topics may be in their own category hierarchies

Or included under a concept or task, or at the end of a task branch, when the reference topics are only useful in that context



Navigation integration demonstration

Pull concepts and tasks into navigation without changing links



Review: Phase 2 - Developing architecture




4. Integrate topics into navigation scheme



Phase 2 Feedback

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.



Phase 3 Feedback

To assist with getting user feedback on your design and topics:

Add a feedback link to every topic during output processing

Validate your role descriptions with users

Tie technical support information (problem reports, FAQs) back into the information lifecycle



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

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

november 2005 © 2005 ibm corporation presentation subtitle: 20pt arial regular, teal r045 | g182 |...

Documents