Monthly Archives: March 2007

Flashback: A Year Ago This Week on Tyner Blain [2006-03-31]

driver mirror

Feature Driven Development (FDD) Explained

requirements class

Feature driven development is a process that begins with high level planning to define the scope of the project, which then moves into incremental delivery. Each increment of delivery involves a design phase and an implementation phase. The scope of each increment is a single feature. Extreme programming (XP) is a much better known agile methodology. XP is often described as an emergent design process, in that no one knows what the finished product is going to be until the product is finished. FDD, by comparison, defines the overall scope of the project at the beginning, but does not define the details.

Passing the Wrong Whitebox Tests

broken link in chain

We’ve talked about the value of using whitebox testing in our Software testing series post on whitebox testing. What we haven’t explored is how to make sure we are creating the right tests. We have to validate our tests against the requirements. This post shows where the flaw is in the typical whitebox testing process, and how to fix it.

A reader emailed us with the comment, “It’s been my experience that developers can’t test their own code.” Their problem was that they were missing a link in the software development chain (missing a step in the process).

Four Application Development Outsourcing Models

The man behind the curtain

There are two distinct types of outsourcing. Bringing experts into our company, or sending work out of our company. Experts who join our team are “temporary team members” not “outsiders.” Sending work outside requires that we address several issues in communication, expectations, and accountability.

We will focus on the models for sending some of the work outside our company, to a team that operates in a very distant location and timezone.

Agile Release Planning With Games

monopoly money

Leading Answers, an agile project management blog, has a great article that details some agile techniques for release planning exercises.  Their article includes explanations and great diagrams.  Check it out.

We haven’t done any of these particular exercises, but really liked the article and ideas.  Especially the transition from the “Remember the Future” exercise to the “Shape the Product Tree” exercise.

Anyone tried these agile release planning techniques before?  Have any success or horror stories?

How To Use UML Statechart Substates

submarine

UML Statecharts can be very effective modeling tools for describing systems and software requirements. They provide a clear framework for identifying business rules. The same business rules often apply to multiple states – defining a commonality for those states. There is an element called a substate in UML statecharts that can be used to make it more obvious that a particular business rule applies to multiple states.

A Simple UML Statechart

We documented business rules with a UML statechart in a previous article, that describes the possible states of a customer order. Those states are saved, placed, charged, shipped, delivered, and cancelled.

uml statechart 1
We defined a series of transitions and talked about the rules associated with those transitions. Imagine that the business rules changed, and customers were allowed to cancel orders even after they had been shipped (as long as they hadn’t been delivered).

Commonality In UML Statechart States

This could serve as an indication that there is a relevant commonality between the states: placed, charged, and shipped. All of these states represent an order that is “in process.” The customer has officially asked us for something, we have not delivered it yet (from the customer’s perspective), and the order has not been cancelled.

You can think of our states as having a hierarchy. You can create a state called “In Process” that generalizes the three states placed, charged, and shipped. By introducing this notion of generalization, we create “substates.”
uml statechart state hierarchy
UML Statecharts allow you to draw these substates inside of a larger superstate. The superstate is drawn with a rounded-corner rectangle, like the other states – but it includes a horizontal bar at the top that allows you to easily show the name of the superstate, separated from the information describing the substates.

UML statechart substate
Notice that the transitions between the substates are the same ones that were defined when the “In Process” superstate did not exist. You can have transitions between substates, and to and from substates to other states that are outside of the superstate. You can also have transitions that go directly to or come directly from the superstate.

uml statechart 2
Notice the single “cancel order” transition that comes from the superstate, In Process. This represents that the transition can be from any of the substates of In Process. The “deliver order” transition can only come from the Delivered substate. The transition “submit order” goes directly from the Saved state to the Placed substate.

Summary

The technique of using substates within UML statecharts allows for cleaner documentation when there are notions that present commonality (like business rules) that justify generalizing multiple states into a single state. This technique allows you to reduce the number of business rules that you must maintain, and makes the diagram easier to read.

How To Start The Use Case Process For Agile Software Development

racing

One of the goals of agile software development is to deliver value quickly and iteratively. One of the most effective ways to begin the software development process is with use cases. [Note: feel free to substitute “user story” or “user scenario” here, if it is more germaine to your process – the idea still applies.] To deliver with agility, you start with the most valuable use case, bang it out, and then move on to the next most valuable use case. How do you know which use case is the most valuable if you haven’t defined all the use cases first?

The Actual Start, Before The Start

before the start of the race

The process actually starts with defining goals and scope. In our earlier article, we referenced Suzanne Robertson’s approach to managing scope definition with stakeholders. While her article was targetted at the “you suddenly realize you can’t finish” problem, the same approaches for “defining the scope to begin with” can be used.

Use cases are driven by goals. And the scope of the product or project can be expressed in terms of the goals that it sets out to achieve. For the rest of this article, assume that the goals and scope have been defined.

Just Start Writing Complete Use Cases

Some teams are inclined to just get started. They recognize the catch-22 of prioritizing by value when defining use cases. You have to define the use cases in order to know which ones are the most valuable. Only then can you pick the most valuable ones to define.

Imagine that the “defined scope” is a picture. Doing work on use cases exposes part of the picture to you. The “scope” defines the size of the picture, but tells you nothing about the content of it. Your goal is to implement the most valuable use cases first. With the picture analogy, your goal is to expose the portions of the image most likely to make it distinguishable.

If you just pick a use case, and define it completely, you get to expose a section of the picture perfectly. Unfortunately, you have nothing to guide your initial selection. Metaphorically, you end up with the following:

partially exposed image

Any idea what the image is?

Write All of the Use Cases First

Other teams will practice BUFR (big up-front requirements) processes. They can be “assured” that what they work on first will be the most valuable thing. The problem is, they are deferring their agile practice (and its benefits) to the development phase. And arguably, they are defeating a driving principal of incremental delivery – get feedback that refines requirements and prevents wasted effort.

This takes more time, but ultimately you end up with the entire picture before writing any code.

[linked image]

Unfortunately, after investing a lot of effort, there is nothing to deliver (except documentation) – and the goal is to deliver software. Besides, by the time you start delivering against the completed (and expensive) use cases, you may find that the customer actually wanted [another image]. At least with the “just pick something” approach, you will quickly find out that your requirements were wrong, and fix them.

There is a better way.

Breadth First Use Case Definition

You can take an iterative approach to developing use cases that is neither of the previous examples. You can define the entire scope of use cases (like BUFR), but at a very low level of detail (not like BUFR). And you can do that faster than you can define the initial use cases.

Start by defining the use case names. Then define very rough outlines that describe essentially what the use cases represent. This level of detail provides guidance and some insight into the relative value of the use cases. In keeping with our picture-discovery theme, this would be the equivalent of a complete, but extremely blurry view of the product scope.

very blurry photo

While this still represents incomplete information, the breadth of information allows you to make much better decisions about which use cases to define first. Your first iteration, instead of completely defining four use cases (or four sections of the photo) may be made up of only two use cases plus the set of use case names. The chances that you’ll implement valuable use cases are much higher.

exposure plus blur

Some of you may still not know what the image represents, but many more of you will. [link to full image]

Summary

Breadth first, then depth. Use case names (and rough outlines or descriptions) can be quickly defined, and coarsely valued. The most valuable ones can be selected for implementation first. This is the key to defining use cases (or scenarios or stories) in an agile software development project.

We believe this is one of the cornerstones of developing an agile requirements process.

Writing Incomplete Requirements

incomplete puzzle

Writing Complete requirements is one of the twelve elements of writing good requirements. Sometimes, you don’t have the opportunity to finish the job, and are forced to write incomplete requirements. How would you go about doing that?

Limited Time For Writing Requirements

Some projects dedicate enough time to define the requirements. “Enough” is a subjective term, but the precise definition isn’t the point. Your project probably doesn’t allocate enough resources to do everything you want with requirements. Also note – this is not an iterative vs. non-iterative discussion. BUFR (big up front requirements) have an obvious and easy to measure allocation of time and resources dedicated to requirements management. Agile processes and approaches that define “requirements as you go” also allocate time and resources to requirements management. It might not be tracked as such, but the allocation is still there.

timebox

Regardless of the process you choose, your requirements gathering activities will want to exceed the allocated capacity. In our article about managing software delivery with timeboxes, we presented four alternative solutions:

  • Increase Time to finish everything.
  • Increase Cost / Resources to finish everything.
  • Finish a subset of the work.
  • Reduce the quality of the deliverables.

A single deliverable is a combination of both content and quality.

quality and functionality

By analogy, the same is true of requirements. You can deliver a use case poorly or well. Delivering it well takes more time.

Finishing A Subset of the Requirements

There are times that you can’t increase staff (or when Brooke’s law prevents that from being effective). There are times when you can’t delay the product. This leaves you with two choices – reduce quality or reduce quantity.

Suzanne Robertson has just written an article at the Requirements Networking Group site describing how to approach reducing the quantity. Suzanne’s approach involves working with stakeholders to identify which requirements to write first. Check it out.

The first comment there raises the point that this may be impractical – to deliver less than was promised. It is a very valid concern, and one of the areas that many iterative projects struggle with. Join in on the conversation there or here.

Three Types of Requirements Gathering

requirements team

There are many different activities that are a form of requirements gathering. So many that it can be difficult to determine which approach to use in what circumstance. By classifying requirements gathering into three different types of activities we can simplify the choices.

The nature of a requirements gathering task should affect the mindset with which you approach it. Some tasks are “do it like this” tasks, while others are “you’re the expert – tell me what I need” tasks. Very different approaches to solving problems. We’ve presented ten requirements gathering techniques in the past. In this article, we categorize the situations in which many of them are more effective than others.

There is an over-arching or over-riding goal of only doing extremely valuable work. That will frame your choices about what requirements to gather. Any given product or project may have one or all of the following.

Gathering Existing System Business Requirements

analysis

In a migration project, the goal is to improve the way a company is doing something they are already doing.

migration project continuum

There is a continuum that defines the boundaries within which the new system will be deployed. Essentially a massive design constraint in the form of explicit charter and often implicit budget limitations. The location of a given project on the continuum will determine how many of the requirements for the new system are expressed as “do it like the old system.”

The requirements gathering techniques that are most effective in this environment are the ones that help you identify the existing system’s behavior and requirements. Has anyone ever worked on a project where someone said “Here are the requirements we used to build the old system. Use these.” [A few hands pop up.] In how many of those projects did the requirements match the existing system? [Hands go down. Groans and chuckles and mumbles wash across the blogosphere.] And for the three people with thier hands still up – “And were those requirements still relevant?” [Roaring applause from completely swayed audience, followed by many links from other bloggers.]

In the real world, you have to validate, rework, and define for the first time the requirements that describe the existing system. Here are techniques that work best in this situation.

  • Document Analysis. Those old requirements documents will have good information, as well as bad. Analyze the docs to find the gems. Also review training procedures, OOA/OOD diagrams, online forums, or call-center knowledgebases.
  • Interview Subject Matter Experts. Interview the people who truly understand how the existing system works. These could be experts on the implementation (the developers who wrote it), people responsible for compliance or policy adherance, or simply the lady who remembers everything (correctly).
  • Reverse Engineer Existing System. Document analysis may not get you completely there – you may have to [shudder] review the source code to figure out what is actually happening.
  • Existing System Interface Analysis. An analysis of the user interface is the black-box equivalent of reverse-engineering the source code. The system has an event-response model of some sort. Map out the behaviors that the system exhibits in response to inputs and events.
  • Observation. Ethnographic research is the study of users as they use an existing system. Watch how people do the work today. In addition to understanding the application better, it will present you with insights about the frequency of use of particular functionality.

This type of requirements gathering can be both difficult and thankless. Project sponsors have been known to say “make it like that.” and expect that that would be sufficient requirements definition. People (who haven’t gathered requirements) assume that if there’s a working version already in place, then defining the requirements to recreate it will be simple. It isn’t. There are often implicit requirements that are not obvious from reverse engineering an application.

Business analysts will run into this type of requirements gathering when displacing legacy applications. Product managers will additionally run into this form of requirements gathering when performing competitive assessments.

Gathering Known New Business Requirements

interview

When a project has been funded, or a decision to create a new product has been made, there are already some well defined goals if not lower level requirements. Responding to an RFP (request for proposal) provides the first opportunity to gauge these “known” requirements. Usually the language of the RFP will tip the hand of the client, revealing their preconceptions and expectations.

The requirements gathering techniques that differentiate themselves for this type of requirement gathering are the ones that focus on communication. SME interviews help you reverse engineer an existing system and understand operating constraints. Interviews with other interested parties at a “step up” in perspective are the key here.

Gathering Unknown Business Requirements

brainstorming

Exploration of the unknown can be the most exciting part of product management and business analysis. The most concise difference I’ve come up with between the two is that product managers focus on extrapolating value and opportunity across customers to define a market, where business analysts are focused on the needs of a single customer.

  • Brainstorming. Brainstorming removes the barriers of conventional thinking and can uncover great ideas, and really bad ideas that inspire great ideas. Brainstorming promotes lateral thinking that uncovers ideas that may be missed otherwise.
  • Idea Seeding. Idea seeding introduces constraints into a “brainstorming-like” activity to make it even more effective.
  • Prototyping. A physical (or visual) model often inspires people to great ideas. It also is very effective at validating your great ideas after you’ve had them.

Hat Tip

Thanks David for your article on the three types of requirements – concious, unconcious, and undreamt. It inspired us to flip the easel and write on the other side of the paper.

Summary

Every requirement gathering technique can be applied to any type of requirements gathering activity. Some techniques will be markedly more effective than others. The makeup of your team will affect the overall effectiveness of each technique. Our experience has been that these approaches are most apt, given roughly equivalent effectiveness with each technique.

easy

They simply make the job easier.

Flashback: A Year Ago This Week on Tyner Blain [2006-03-24]

driver mirror

Interaction Design Process Overview

businessman on laptop

Interaction design, as described by Alan Cooper in The Inmates are Running the Asylum, is a process for designing software by focusing on the most important users. Unlike traditional requirements gathering and solution design processes, interaction design focuses on the goals of a specific class of users, represented as a persona. Those goals are considered when defining scenarios that represent how the primary persona will use the software. The combination of goals and scenarios leads to design artifacts and a functional specification. We will explore these steps in more detail in this post.

How To Create Personas for Goal Driven Development

Artist creating personas

We mentioned the creation of personas in our overview of the interaction design process. In this post we will talk in more detail about how to create them. We will cover identification and prioritization of the personas, defining the practical and personal goals for the personas, and creating the anecdotal stories that give each persona an identity against which we can make design decisions. Scenarios are also defined for the primary personas, which drive the creation of the functional requirements specification.

Interaction Design and Structured Requirements

Borg queen

Wiegers promotes structured requirements. Cooper touts Interaction Design. Both have great ideas. Both “wave their hands” at different parts of the process. In this post, we’ll talk about how to combine the two philosophies to get the best of both worlds.

Don’t Make Your Products Too Simple

blocks

Joshua Ledwell wrote a short article expressing his perspective on designing software that is neither too simple nor too complex. He also links to some excellent other articles on the topic.

Designing For Competent Users

We’ve written in the past about how to design for competent users. In fact, it was Joshua’s link to that article that helped us find his article – thanks! Users start out as novices, and most of them become competent users. Very few of them reach a level of expertise with your product. You need to make sure you support both their growth and their likely “end state” – competence. The feature set needs to support the fact that most users end up in a state of competence.

Maximizing ROI

One of several good links from Joshua’s article took us to Luke’s article on the sweet spot for selling software. Luke references an article from the Harvard Business Review and includes an interesting graph that shows the relationships between the number of features and profitability. In short, more features drive higher initial sales by satisfying the buying persona. Fewer features drive higher eventual sales through word-of-mouth marketing based on improved usability.

The HBR suggests a profit maximizing approach of seeking the middle ground in terms of feature quantity. Trying to please everyone tends to result in pleasing no one, so we don’t have a lot of confidence in this approach. But we still like the graph.

Some great thinking out there, what do y’all think in here?

UML Statecharts and Documenting Business Rules

turtle seeking the ocean

In yesterday’s article we compared use cases and UML statecharts as tools for discovering business rules. James Taylor asked a question about how we would document those rules, and then followed up my comment response with an article about business rules and RUP. In this article we move the conversation slightly forward – recognizing that we’re slowly entering the ocean of business process management.

UML Statechart and State Transition Table Artifacts

There are two primary artifacts that come from using a UML statechart to discover business rules. The first is the statechart itself.

uml 2.0 statechart

This is a primary artifact from the perspective of object oriented analysis (OOA). It provides a large amount of information in a dense, yet incredibly easy to absorb format. It is the ease of understanding that makes this a great tool for validating your understanding of the business process with stakeholders.

There are three elements of information that are documented in a UML statechart. The first is the list of possible states. In the example above, the rounded rectangles represent the possible states for a customer-order (Shipped, Delivered, etc). The second is the exhaustive list of all allowed state transitions (“Deliver Order” is the event that causes a transition from Shipped to Delivered). The third element is the events that describe (or cause) the state transition. “Deliver Order” is one of them.

Note that there can be multiple events that cause transition between the two states. If you modify the example above as follows…

uml statechart double transition

You can document that either the customer, or the supplier (of the products for the order) can cancel the order.

There are two failings of the UML statechart. The first is the lack of support for rule discovery, and the second is that it is a poor framework for trying to document the business rules for later consumption.

State Transition Tables

You will have already created a state transition table as part of validating the completeness of your UML statechart. This is how the lack of support for rule discovery was addressed.

state transition table

[larger image]

In the comparison of UML statecharts with use cases, we made a small reference to documentation of business rules.

Each possible transition has a number – which provides a reference for defining the business rules associated with each transition. You could put the rules inside the boxes, but the numbers make the table much easier to read.

In this example, #3 represents the allowed transition of the customer-order object from the state of Placed to the state of Charged.

What You Need To Document

To document the business rules associated with a UML statechart, there are five elements that must be documented.

  1. Defining The Object. The definition and relevance of the object being described.
  2. Listing The States. The list of possible states that the object can be in.
  3. Defining The Rules of State. The rules that in force when an object is in a single state.
  4. Listing The Transitions. The list of allowed state transitions that the object can make.
  5. Defining The Transition Rules. The rules that govern the transitions from one state to another.

Defining The Object

A definition of the object is important to establish the context in which the business rules are being applied. Remember that this is a business object (a customer-order), not an implementation detail (class CustomerOrder :: Object). The description of the object and rules that define it will be in the language of the business, not implementation details.

Listing The States

You already have the list of states explicitly in the state transition table, and you could create it from the UML statechart. If you only had to list the different states, there would not be any value to creating an additional list – just reference the table.

Defining The Rules of State

Each state that the object can be in has a set of business rules associated with it. These are rules in addition to the rules that define the allowable transitions (more details below). Here are some example business rules of state.

  • Suppliers can view orders that are in the Charged or later states.
  • Suppliers can only view orders that include products that they supply.
  • Customers can edit orders that are in the saved state.

Listing The Transitions

The allowable transitions are implicitly defined in the state transition table. Each allowable transition has a reference number (or ID) in the table. Every transition is also displayed in the UML statechart. If there were no rules associated with the allowable transitions, the table could have been done with yes/no boxes instead of references.

Defining The Transition Rules

Each allowable transition will have some rules associated with it. What initiates the transition? What constrains the transition? Here are some example business rules that govern the transitions from one state to another.

  • An order will only be shipped when it can be completely fulfilled.
  • An order will not be charged unless the customer has provided a valid shipping address.
  • Orders will only be charged when the shipping address is in the United States of America.
  • A charged order will be cancelled if it has not been shipped within ten business days.
  • A saved order will be deleted if it has not been submitted within 90 days.

These business rules are important to the company. It is important to document them.

Scott Ambler shows a way to include this information within the UML statechart. His Figure 1 example demonstrates how to do it for object oriented design (the implementation design) and includes references to java functions that may be called. The concept could be applied to OOA diagrams as well.

We would encourage you to not include the rules within the diagram, as practicioners of Scott’s own advice – “I prefer to follow the AM practices Depict Models Simply and Model in Small Increments.” The extra information in the diagram makes it unwieldy. In our experience, a concise diagram with accompanying text is a better communication vehicle than a standalone diagram with higher information density.

Practical Application of This Approach

There are many systems for documenting and managing requirements and business rules. Forrester and The Gartner Group have even changed the name of the space from “Requirements Management (RM)” to “Requirements Documentation and Management (RDM)” in their communications. Generally, the solutions in the RDM space either use a repository to store information in a structured format, or they manage individual documents as artifacts.

Individual Document Approach

When your team is using individual documents to manage requirements, we suggest that you create a single text document that includes the text descriptions of states, transitions, and rules. This document should also include the UML statechart and the state transition table. These objects can be embedded or referenced to prevent the dual-maintenance problem of updating the text “wrapper” document whenever the underlying object changes. When using Microsoft Office, a Word document can include both the Visio and Excel objects by reference. HTML documentation will include the objects by reference. There is no really “clean” way to manage individual documents, and certainly no standard way to do it. Whatever works for you should continue to work. The goal is to present a single document (the “wrapper”) that contains or references all of the relevant information – prose + UML statechart + state transition table.

Requirements Repository Approach

If you have a repository that has been customized to specifically deal with UML statecharts, transition tables, and supporting rules, you’re ahead of the game. Please tell us about it too. As far as we know – it doesn’t exist.

Most structured RDM tools allow users to attach files to “requirements” objects. They also allow for the notion of supported and supporting “requirements” – either through traceability or composition. In the rest of this explanation, the term “requirement” is a reference to whatever artifact, object, or container the particular RDM tool uses to encapsulate a discrete business requirement or rule.

You can create a requirement that represents the business object and includes the contextual information describing the object (customer-order in this example). The list of states that the object can be in should be included in this requirement.

In support of that requirement, you should create other requirements that represent the defined business rules (#3 and #5 in the list) as separate objects. You separate the objects so that each requirement is atomic. The UML statechart and state transition table should be attached to the “wrapper” requirement as references. The diagrams, in this approach, are providing clarifying but redundant information. They need to be identified as such, so that in the event of misinterpretation (or requirements becoming out of sync), there is a clear “winner.”

Summary

There are many business rules associated with a business object that can change state. Those rules define the interpretation and ramifaction of being in a state. They also constrain and enable the transitions between states. The list of states and possible transitions are also business rules of a sort – although they may be better described as decision services than business rules.

Documenting these rules is important. You shouldn’t try and cram the documentation inside the diagram or the table. You should use accompanying prose.

Use Case vs. UML Statechart – Business Rules

soccer trip

What is the better requirements management model for capturing business rules? The use case, or the UML statechart? In this article, we explore how customer orders are submitted and processed, and contrast how use cases and statecharts expose and document business requirements and business rules.

The Scenario

To set up the comparison between use cases and statecharts, consider a website for a company that sells products online. Customers can create orders and submit them. The company will process the order and ship it to the customer. You need to define the requirements.

When gathering requirements, you learn the following:

  • The company wants customers to be able to save an order and come back later (like Amazon’s shopping cart) to complete it.
  • When a customer submits an order, the company will charge the customer (credit card, paypal, etc) through an outsourced billing service provider.
  • The company doesn’t ship the order until after the charge has been made successfully.
  • The company wants customers to eventually be able to track their orders by providing them with a tracking number from the third-party shipper that they use.
  • The company also wants to be able to track their “work in progress” inventory and analyze their pipeline. To them, that means they want to know how many orders have been saved (but not submitted), how many orders have been submitted (but not shipped), how many orders are being processed, and how many have been delivered.

The Use Case Example Analysis

If you take a user-centric approach to documenting the requirements, you should start with the most important use case – Customer Orders Products.

Customer Orders Products

Actors:

  • The customer – user who purchases products from the company.
  • The system – the software with which the customer interacts.
  • The billing-provider – an external system that is responsible for billing transaction processing.
  • The fulfillment system – an internal system that is responsible for shipping purchased products to the customer.

Use Case Steps:

  1. The customer selects products to purchase.
  2. The system adds the products to the order.
  3. The customer submits the order.
  4. The system requests payment for the order from the customer.
  5. The customer provides payment information.
  6. The system requests payment for the order from the billing-provider.
  7. The billing-provider acknowledges payment processing.
  8. The system notifies the customer of successful payment.
  9. The system submits the order to the fulfillment system (another system at the company).
  10. The fulfillment system ships the order [note: this would likely be a subordinate use case].
  11. The fulfillment system notifies the system that the order has shipped.
  12. The system notifies the customer that the order has shipped.

There would also be an alternate case (use case extensions) allowing the user to save an order in-process and return to complete it later.

During the review of this use case with stakeholders, you would uncover the need for customers to be able to cancel an order at any point prior to shipping the order (step 10).

This use case analysis gives you the framework for designing the user interface of the system, and for defining functional requirements. Starting with a use case does not prevent you from gathering all of the business rules associated with customer ordering, but it also doesn’t help very much with some requirements.

Using a UML statechart provides a different view on the requirements.

Into To UML Statecharts

state machine controls

UML 2.0 statecharts, also known as state-machine diagrams and state transition diagrams, are designed to show how an object can change its state of being over time. When documenting requirements, you would create a state chart for a business object, in this example, a customer-order. The UML statechart would show all of the possible states that an object can be in, and all of the possible transitions, or paths, that would allow the object to change from one state to another.

The following legend shows the four primary elements of a UML 2.0 state chart.

statechart legend

The UML statechart starts with a solid black circle, and has a transition to the first of the possible states. The transition is the action or event that causes an object to be created or change state. In the legend above, the act of saving an order causes the creation of a customer-order object in the saved state. Near the end of the diagram (the middle is removed), a “Deliver Order” transition causes the customer-order object to change to the state “Delivered.” The end of the process is designated with a solid black circle wrapped in a thin line.

A much more thorough introduction to UML statecharts can be found at Scott Ambler’s awesome site. Ambler’s introduction includes other statechart elements, nesting of statecharts, and more complex examples. Good stuff.

The UML Statechart Example Analysis

If you had approached the requirements from a system-centric or rule-centric point of view, you might have started with the creation of a UML statechart for the customer-order object. You could also start with a process flow diagram of the customer ordering process – but that has more in common with the use case analysis.
The customer-order object is a conceptual object that represents the order that the customer is trying to place. While it is very likely that the implementation will be designed with a customer-order object too, you are not describing the implementation – you are describing the requirements.

Your first drawing of the UML statechart might look like the following:

simple uml statechart example

The obvious path is clearly defined in the statechart:

  1. A customer order is created in the “Saved” state when the user saves it.
  2. When the customer submits the order (use case step 3), it changes state to “Submitted.”
  3. When the customer is charged for the order (use case steps 4 – 8), the order changes state to “Charged.”
  4. When the order has been shipped (use case step 10+11, or just 11), the order changes state to “Shipped.”
  5. When the order has been delivered, the order changes state to “Delivered.”

During the review of this UML statechart with stakeholders, you would uncover the need for customers to be able to cancel an order at any point prior to shipping the order. Three additional transitions are defined, leading into a new state, “Cancelled.” If the user deletes a saved order, or cancels an order that has been placed but not yet shipped, the order’s state is changed to “Cancelled.”

Viewing the UML statechart for the customer-order object still doesn’t help uncover more requirements. Joe Shideler presented a great requirements model – a state transition table on Seilevel’s blog in late 2005. The table presents a view of possible state transitions that gets your brain out of the linear mode that it is in in either of the above situations.

A State Transition Table Example

Creating and populating a state transition table for the customer-order object would look like the following:

state transition table

[larger image]

Each row in the table represents a starting state (the tail end of a transition in the diagram). Each column represents an ending state (the arrowhead end of a transition in the diagram). To read the diagram – you can see that transitions from the “Saved” state are possible to both the “Placed” state and the “Cancelled” state. Transitions to the other states are not possible – indicated by the “X” and light grey shading in each cell.

Each possible transition has a number – which provides a reference for defining the business rules associated with each transition. You could put the rules inside the boxes, but the numbers make the table much easier to read.

In some situations, it is possible for an event to cause a transition into “the same state.” An example would be if a customer desired to split one order into two orders based on shipping lead times. The “transition” is actually from one object to two other objects. Ambler shows an example like this, but it doesn’t apply in this example. The dark grey shading and bold “X” represent that an object can not “change” into the same state.

Why State Transition Tables Help Uncover Business Rules

The table above is already populated with the final answer – and you’ll notice that it shows some valid transitions that are not indicated in the UML statechart above. Populating the table forces you to consider each possible transition. As part of that consideration you are more likely to uncover “hidden” requirements than if you were only reviewing a linear model like a use case (or the previous statechart).

It is possible that an order is shipped to the wrong address, or not shipped at all. Mistakes happen. The company wants to be responsive to customers, and has defined specific business rules and policies for handling this situation.

You can update the UML statechart to show the additional transitions that must be supported:

complete uml statechart example

Is The Statechart Better Than The Use Case?

Yes and no. For defining interface requirements (both the user interface and system interfaces) the use case is much more effective – it describes, by definition, the series of events that happen. However, it is biased towards documentation of the normal flow of events. Exceptions, errors and alternatives can all be documented with use cases, but it becomes harder to consume – because the use case triggers a linear analysis through the process.

When striving to achieve requirement completeness, an additional perspective is required. A statechart can provide a two-dimensional perspective of the process. It is object focused (with actions as transitions), versus action-focused. As this example has shown, the statechart can be presented in an equivalent form to the use case – very linear.

The state transition table forces you to think outside of the linear flow of the obvious course of events. You don’t have to brainstorm about “what might go wrong” – you systematically explore all of the potential state-transitions. Each transition is either explicitly excluded (with an “X” in the table cell) or explicitly included. The risk of missing a transition and its associated requirements is dramatically reduced.

The identification of all valid transitions is the first step in defining the business rules that control each possible transition.

The state transition table, while very effective for analysis, falls short of the UML statechart in presenting the results. A good practice is to update the statechart with all transitions identified in the table.

Conclusion

The use case and the UML statechart provide different views on the same requirements. Using one without the other risks missing requirements. The use case helps define interfaces with users and external systems. The statechart helps define hidden paths (alternate flows).

The state transition table is the most rigorous tool I know of for explicitly defining the valid transitions. But it is not a good communication tool. The results from use of the state transition table should be presented in the UML statechart. This solid set of transitions is the foundation for defining business rules and business requirements.