Home/Publications/Best Practices Newsletter/2012 – Best Practices Newsletter/Using Scenarios to Develop Accurate, Reliable Information in an Agile Development Environment


February 2012

Using Scenarios to Develop Accurate, Reliable Information in an Agile Development Environment

CIDMIconNewsletterMark Farmer & David Epstein, IBM Corporation

Textual narrative scenarios provide a means to clearly articulate the scope and work flow of software by using real world examples. Scenarios can be collaboratively developed with key stakeholders, including end users, developers, and business partners, to ensure that they are accurate and complete. Scenarios can also be developed over time to reflect the changing requirements of the product.

A scenario is a story about how a user performs tasks to achieve one or more goals. A scenario is written in the users’ language, using their own terms. A fully formed scenario should include four elements. It should describe the users’ personas, the tasks they need to carry out, what they are trying to achieve (the goals and business problems), and the environment in which they perform these tasks.

Scenarios are a key source of information that can be used to drive the development of the product and the associated documentation. In practice, how can this be achieved? Particularly, how does the use of scenarios fit in with the multi-iteration, Agile development model?

This article emphasizes the importance of scenario-driven development, while highlighting its many advantages. The article also introduces tools to help develop and maintain scenarios throughout their life cycle. The suggested work flow is based on the Agile methodology, which uses short iterations to modularize the software and information development tasks.

As an example, we describe the development of KwixiPix, a tool for manipulating digital photographs. In this example, the development is spread across six iterations. To develop the scenario and associated model, we will use IBM Information Architecture Workbench (IAWB) and its Scenario Analyzer component.

IAWB, formerly known as Task Modeler, is a free, Eclipse-based tool for graphically designing, building, and editing DITA maps and relationship tables. IAWB enables you to

visualize various properties of the map, such as the linking between files.

You can use IAWB to perform tasks such as:

  • Visually design and reorganize topics in a map
  • Automatically generate initial DITA topic files
  • Visualize the relationships among topics
  • Visualize and edit properties of the DITA map and topic files
  • Design, edit, and visualize relationship tables
  • View a summary of how a topic will look after it is transformed into HTML
  • Preview the related links that will be generated for a topic
  • Identify unreferenced topic files and import references into the map
  • Synchronize the DITA map metadata with the topic file metadata
  • Export reports listing information about all the topics in a map

IAWB creates attractive, expressive diagrams that inform and engage design stakeholders.

Scenario Analyzer is a component of IAWB that enables you to efficiently create and analyze narrative scenarios. It supports the classification of phrases in the scenario text to a pre-defined type of object. The analyzed and classified scenario can then be used as the starting point for further work with other tools, such as IAWB. Scenario Analyzer can be used in conjunction with IAWB to create hierarchical models based on the evolving scenarios. You can use these tools to help maintain the relationship between the scenario and resulting model to ensure that they accurately reflect and complement each other.

Iteration 1: Develop an initial scenario for how users will use KwixiPix

The development team works with the key stakeholders, such as business analysts, partners, and potential users, to create the initial narrative scenario that describes how customers will use KwixiPix. They create the scenario directly in Scenario Analyzer rather than creating the scenario in another application and importing it into Scenario Analyzer.

Once the text of the initial scenario is established and agreed upon, the stakeholders can analyze the text in more detail. Scenario Analyzer allows you to identify phrases in the scenario. Phrases are one or more consecutive words that describe a part of the scenario. Each identified phrase is classified as a particular type, such as a DITA task, concept, or reference. For example, the phrase “Import Photo into KwixiPix” can be identified as a task. Scenario Analyzer visually highlights the identified phrases. After our example scenario text is analyzed, several tasks, concepts, and references are identified as shown in Figure 1.


Figure 1: Scenario Text with Identified DITA Tasks, Concepts, and References

These elements are used in the next iteration to create a model of the scenario.

Iteration 2: Create a model (DITA map) to structure the scenario

The next step is to understand the relationships between the elements that were identified in the scenario by using IAWB to create a hierarchical model of the information. Within IAWB, create a DITA map and import the scenario elements as topic references. After the elements are imported, the topic references are automatically organized into a task flow to establish parent, child, and sibling relationships among the topics. The IAWB map editor provides a highly visual, interactive, and collaborative framework for further map development.

After a map is created from a scenario, Scenario Analyzer maintains the relationship between the scenario and the models, and IAWB can show these relationships. For example, if you select the “Import Photo in KwixiPix” phrase in the scenario, the associated topic reference in the map is highlighted.

After the map is established, the development and UX teams can use it to develop the work flow of the KwixiPix user interface. In parallel, the information development team can use the map as an initial information structure. The information architect can extend the map by creating initial relationship tables to define further links between the topics, using the visual Relationship Table Editor in IAWB. The architect can also use IAWB’s property visualization techniques to efficiently and accurately validate the topic relationships.

Iteration 3: Start to author the topics

The information developers now use IAWB to author the topic contents. First, you automatically create stub topic files for all topic references in the map. Then you navigate through the map and open the topic files in a preferred DITA topic editor. As content is added to the topics, you can change the status of the topics to enable you to track your progress. For example, the map shows that the “KwixiPix suggests red-eye” task topic has not been written yet, as shown in Figure 2.


Figure 2: The Topics in the DITA Map, Shown in Different Colors to Represent the Topic File Status

When you select a topic reference in the map, the source phrase in the scenario text is also highlighted. This mapping between the scenario text and the map illustrates an advantage of using scenario-driven development: The initial scenario can be directly used as a basis for content authoring and can help authors to better understand how a topic fits into the big picture. Because the scenario was developed and agreed upon by key stakeholders, using the scenario as a basis for the content of the topic can greatly improve the quality of the content.

During the topic authoring phase, IAWB provides an HTML rendering of the topic file. This rendering serves as a preview of how the topic will look after transformation to HTML. IAWB uses the DITA Open Toolkit to render the topics.

Iteration 4: Revalidate the scenario with the stakeholders

Of course, in the Agile world, things will change as development proceeds. For example, the stakeholders might have added a new section in the scenario. This section contains additional tasks and concepts. This new scenario section describes more advanced photograph manipulation techniques, such as identifying additional concepts to “Sharpen” or “Blur” the images. Scenario Analyst allows new sections of text to be collaboratively added to the scenario. Because the scenario is the source of the DITA map, these new concepts also need to be added to the map.

Scenario Analyzer identifies that the scenario and map are now out of sync. The information architect can intuitively import the new scenario elements into the map to synchronize the scenario and map content.

In the map, the architect moves the new Sharpen and Blur concept to the appropriate part of the map. Stub files can be automatically generated for the new concept topics and the author can add content.

Because the scenario is used as the directly referenced source of the map, the structure of the map accurately reflects the scenario text. Because the scenario was developed and agreed upon by key stakeholders, the structure and content of the map and any other models derived from it match the stakeholder’s understanding. If the scenario and map are accurate, complete, and concise, the resulting information should also be accurate, complete, and concise.

Iteration 5: Internally review the map structure

The information development team reviews the updated map structure and sees that the map needs further re-organizing. There are several subtasks scattered throughout the map that describe how to change the color palette in the photo image. The architects reorganize the map to bring all these tasks under a common parent task called “Change the photo colors.” Content is then added to this parent topic to describe the overall flow of the related tasks.

Iteration 6: Revalidate the scenario with stakeholders

As the information development process continues, Scenario Analyzer again identifies that the map and scenario are out of sync. For example, the information developers added topics about how and why a user would change the colors in the photo. Because this information was not in the initial scenario, the scenario needs to be re-organized to include a new section describing how to change the colors in the photo. The added text is highlighted as a phrase in the scenario and is linked to the corresponding task and concept topics in the map. Scenario Analyzer reconfirms that the scenario and map are back in sync. The updated scenario is then reviewed and validated by the stakeholders.

Both scenarios and models play a key role in developing products and the associated information. Basing your information model on a concrete scenario helps ensure that both items are well developed. Creating information models from scratch can be difficult and error prone. It can be difficult to know where to start, particularly if there is a large amount of information that needs to be modeled. Narrative scenarios provide a concrete method of describing these more abstract terms in a language and structure that key stakeholders can sometimes more easily understand.

Ensuring that the scenarios and models represent the same information is vital. IAWB and Scenario Analyzer maintain and highlight this relationship, leading to more complete and representative scenarios and more accurate models, which ultimately results in a better product and documentation set.

Working from scenarios and referencing the original scenarios through an entire work flow can help ensure that the product and documentation is accurately grounded in descriptions of real-world accounts. The original scenarios can be referenced throughout a project’s life-cycle, increasing accuracy and accountability of a project. Scenario Analyzer allows scenarios to evolve and develop as projects progress, while ensuring that the resulting work is still true to the original scenario. CIDMIconNewsletter

Mark Farmer

IBM Corporation


Mark Farmer is a software engineer at IBM in the UK, where he has been working for 15 years. During that time, he’s led the development of highly visual, interactive modeling tools for use inside and outside IBM. These tools have latterly focused on supporting information development using DITA, and how that fits into a broader development process.

David Epstein

IBM Corporation


David Epstein is an information developer at IBM in Israel. He chairs the IAWB Advocates, a group of information developers, architects, and other interested users who help clarify and promote use of the tool.