I came across a really interesting article LukeW.com, showing how making changes to the way an input form on a website increased interaction by 25 to 40%. The changes reflect the value of thinking outside-in, investing in user experience, and performance measurement.

Bonus: the idea is cool.

Mad Libs Input Form

[full size image available in Luke's article]

The idea being presented is to replace the old boring web input form designed for a computer. The new, fun form is a fill-in-the-blank (aka Mad Libs) layout. The article is on Luke Wroblewski’s site.  The team at Vast.com created and tested a version of this form for the Kelly Blue Book site. [Luke cites Huffduffer.com as the first place where he saw this technique.] Thanks, Luke for sharing this with all of us!

Outside-In Development

Product managers are acutely aware of the need to solve market problems. We are regularly reminded that we’re creating solutions for people in our markets who use our products to solve their problems. When we write requirements, we avoid writing design specifications, and thereby lose the ability to enforce that the proposed solutions also take an outside-in approach. We maintain an outside-in perspective, but we lost the ability to influence an outside-in aesthetic.

Note: Outside-In Software Development is a great book, you should read it.

That’s one area where user experience works well in concert with product management – assuring that the same drivers of what to build are informing the design of how it is built.

The genius (or at least elegance) of this Mad Libs form from Vast / Kelly Blue Book is that it humanizes the experience of requesting that a nearby dealer contact you to discuss a possible purchase of a car from them. The forms we’ve all had to fill out on countless web sites are very inside-out. They expose the inner workings of the program – “gather this info, and that info, and this other info.” Those forms force users to do what the program wants. Blech. The form that Ron Kurti designed, however, forces the program to do what the users want. Huzzah!

Bad Requirements Prevent Elegance

I’ve written about the importance of writing design-free requirements several times.  Avoiding design constraints in your requirements is even one of the pillars of the big 10 rules of writing requirements.

If you had written the requirements for this contact the dealer page, would you have specified the design of the form?

Most of the requirements analysts I’ve worked with would have. I’ve even worked with companies that have developed templates / stencils defining how these interface specifications must be documented – requiring that all the fields be aligned, with specific pixel gaps, etc.

If you had specified the design (read: limited the choices of the designer), you would have prevented this solution.

Mr. Kurti’s elegant solution is clearly better.

One way to write the requirements that would not have prevented this solution would be with a user story and acceptance criteria:

As a car-shopper, I want to engage a car dealer, once every few years, so that I can purchase the car I selected.

• The car-shopper can provide his contact info (name, email, phone) for the car dealer.
• The system will display the information identifying the selected vehicle.
• The system will display the information identifying the dealer being contacted.
• The system will include an opt-in newsletter-subscription option.
• The system will notify the specified dealer when the car-shopper indicates.

The user story nudges the developers into an outside-in perspective by emphasizing the user’s goal. The acceptance criteria make it clear that any solution that meets those criteria is acceptable to the product manager. It allows the interaction designer to create a compelling solution, rather than forcing him to recreate a boring experience.

Measurement Rocks

The Vast team measured the impact of making this change to their form, and saw between a 25% and 40% increase in conversion (people contacting dealers versus people abandoning the process when they see the form). That’s a lot more leads for the dealers, and presumably a lot more money for Kelly Blue Book and Vast. This is a great example of how you can measure the impact of investing in user experience, because it should spark ideas for you.

What can you measure and test and improve?

Now that’s ROI for you.

You give your requirements to the engineering team, and they look complete.  The team builds your product, you launch it and the market soundly rejects it.  Why?  Because your requirements weren’t complete – they didn’t actually solve the problem that needed to be solved.

Complete Requirements – Revisiting

Going back almost four years, I wrote Writing Complete Requirements, as part of the Big Rules of Writing Requirements series.  That article centered on two key ideas of requirements completeness.

• Data, not opinion, is the most important input into determining completeness.
• There is no absolute way to determine the completeness of your requirements in advance.

Completeness is best measured by market acceptance, so technically you can’t know if your requirements were complete until your customers buy (or fail to buy) your product.  This doesn’t mean you should give up on this rule of requirements – you can still focus on, and improve, the completeness of your requirements.

Objective and Heuristic Assessment

Given a market problem and the associated requirements (which you can argue are actually the same thing), you can review those requirements to determine if they objectively appear to be complete.  This assessment is based on what you objectively know about your market (needs, opportunity costs, competitive alternatives, etc).  You can also apply heuristic, or logical analysis to identify gaps in the language of your requirements.

Objective assessment is the application of market knowledge (data) to determine if the nature of the problem is being addressed completely by your requirements.  A bird-feeding maven would know that the requirements for your bird feeder would be incomplete if they didn’t address the problem of squirrels stealing food from the birds.

Heuristic analysis is the identifications of logical omissions in your requirements, without the need to apply market insights.  A logician would know that the requirements for your bird feeder were incomplete if they didn’t address the need to refill an empty feeder.

When you’re writing requirements, you need to do both.  Heuristic analysis of your requirements will identify where your requirements do not fully solve the problems you already know about – an eCommerce checkout process without the ability to receive payment, for example.  Objective assessment will help you identify the problems that you overlooked but need to solve – the need to allow customers to have different billing and shipping addresses when placing an order online, for example.

Complete Requirements for Incomplete Solutions

Don’t confuse having complete requirements (a good thing) with completely solving a problem (not always a good thing).  In agile development, the idea of satisficing is key to scoping individual iterations.  The idea, simply put, is to solve enough of the problem, and not delay delivery (and value) until you can build a solution to the entire problem.  Because of the law of diminishing returns, for many market problems, there is little or no incremental value in solving the entire problem.  Those resources can be better applied to solving additional problems.

Kano analysis provides a framework for identifying which market problems must be completely solved, and which ones have a more is better characteristic.  In practice, more is better problems exhibit the law of diminishing returns, and should not be “completely” solved.

[larger image, or view the entire Kano analysis presentation]

Conclusion

Complete Requirements are requirements that

• Identify all of the market problems that need to be solved and their nature (absolute vs. diminishing returns).
• Are logically complete in their coverage / articulation of those market needs.

To objectively improve the completeness of your requirements, apply market data in an assessment of your requirements.  To heuristically improve the completeness of your requirements, look for logical inconsistencies and gaps in reasoning or coverage.

Engagement – that’s what this whole product management blogging thing is about.  Check out what Tyner Blain readers found to be the most engaging articles in 2009.

Deep Dives

If you’re new to Tyner Blain, you may be surprised by the length of the articles here.  I joke that they are long because I don’t have time to edit.  Stewart Rogers jokes that they are long because I’m incapable of writing a short article.  If you’ve been here a while, you know what you’re in for.  If you’ve been here a long while, then you’re glad (like me) that I don’t write one per day any more.

Product Management is simultaneously a broad and deep discipline, requiring us to have a breadth of perspective combined with a depth of insight.  We then have to apply that in a market context, effectively navigating the political waters of our organizations.  Most of the articles here either try to skim the breadth of a range of related topics, or plumb the depths of a single topic.  Doing that in under a thousand words is pretty hard.  Most of the articles here also link to other articles, to try and provide even more depth and context, and encourage additional critical thinking.

One measure of the quality of the articles here is how often they stimulate readers to read further, or dive deeper into the topics.  While web analytics won’t allow us to measure how thought-provoking an article is, we can look to see how many people dive into the linked articles, versus how many people move on to something else.  We can measure the bounce rate of an article to see how often people leave a page without following any of the “tell me more” links.

Looking at ~170,000 page views at Tyner Blain in 2009, narrowed down to only those articles with at least 100 page views, here is the top-ten list of most engaging (or “least abandoned” if you’re a “cup is half empty” person) articles:

1. Use Case Series: Introduction: A collection of articles on the “traditional” forms of use cases – informal, formal, UML.
2. Agile Development of Use Cases: A dive into the dynamics and cadence of an agile process for developing use cases.
3. How Do You Manage Market Data?: A collection of articles exploring different market-immersion techniques in depth.
4. Scheduling Requirements Changes – Part 2: A focus on practical techniques for managing change with an agile development process.
5. Yesterday’s BPMN Post Was A Big Fat Lie: A mea culpa and clarification of interest to folks following the BPMN Series.
6. Everything I Needed To Know I Forgot in Kindergarten: Why asking why? is important.
7. Plan Your Next Sprint by ROI – Part 1: Prioritizing by Bang for the Buck, not just Bang.
8. Ten Common Mistakes of Going Agile: A collection of articles about common pitfalls encountered when adopting agile practices.
9. Perpetually Almost Finished Projects: Organizing a project with discrete deliverables and rolling-wave planning to avoid the “90% done, 90% remaining” problem.
10. How To Use Timeboxes for Scheduling Software Delivery: One of my personal favorites.  A rational approach to making trade-offs when your “perfect” plan has to change.

OK Stewart, that’s only 519 words.

Unless you live in a world filled with unicorns and rainbows, writing realistic requirements is critical.  When you set unattainable goals, the best result you can hope for is a frustrated engineering team.  Write requirements that are attainable, and your team will surprise you with what they can achieve.

Attainable Requirements – Revisiting

A little over three years ago (ten unicorn years), I wrote Writing Attainable Requirements, as part of the Big Rules of Writing Requirements series.  In that article, we focused on the unique situations that every team faces – politics and people, and the shared challenge of implicit practicality.  Those factors are as important today as they were then.

Defining Attainable

Attainability, for requirements, is simply the answer to the question – can this be reasonably done?  Most, but not all, of the answer to that question comes from understanding if your team can build and test a solution to the problem you identify with your requirement.  Being able to create a solution requires that the problem you’re solving is tractable, and that the team creating the solution has the skills to solve it.

Being able articulate a problem and it’s solution is necessary, but insufficient – solving the problem requires that there be a feasible solution.

As the founders of the agile development movement explained in their pitch for “low overhead” process – people trump process.  I think it was Alistair Cockburn who added, “but politics trumps people.”

Finally, process is the often-overlooked element of determining attainability.  Realizing the benefits of a novel solution to an existing problem usually involves process changes – sometimes significant ones.

The next few sections go into more detail on each of these – tractability, feasibility, people, and process.

Tractability

Goldilocks ruled out the large bed because it was too large.  Eating the elephant, drinking from the fire-hose, boiling the ocean – these are all common phrases in the American vernacular, because so many people try to do too much (at one time).  There are many ways to decompose a large, intractable problem into smaller, addressable components.  Practicality requires that the problem you’re trying to solve is not too large.

If everything you do is small, however, you won’t ever accomplish anything big.  That’s where strategic product management shines.  As part of understanding your market, you identify large, valuable problems to be solved.  To solve those large problems, you have to break them up into smaller problems, and then address them individually.  You also have to make sure your team understands the big picture and the larger problem that ultimately needs to be solved.  A great way to share context while decomposing problems is with the use of Ishikawa diagrams.

And zooming in…

Maintaining context is a particularly critical component of working with agile teams, where each deliverable’s possible size is constrained further to what a team can accomplish in an iteration.

[click for larger version]

For some problems (and some teams!) this may be enough information to provide the context to develop a product backlog.  And your agile team will move forward into managing their own execution from the product backlog stage.  For larger or more complex problems (such as this example), you will need more detailed communication before diving into user stories / use cases.

The same Ishikawa diagram, with more detail, looks like the following:

[click for larger version]

Agile Product Management: Providing Context

This reduced granularity represents the smallest go-to-market atomic requirement.  Further decomposition results in smaller requirements, but they become too small, because they are no longer independently valuable.  I’m not talking about “the sum of the whole is greater than the sum of the parts” stuff here – I’m talking about “if you only get X, without Y and Z, it has no value” stuff.

Feasibility

Even after decomposing market problems into addressable chunks, you still have to make sure that there are feasible solutions.  One of the brighter software developers I worked with back in the day used to say “We’re writing software – it’s all ones and zeros – we can do anything.”  He also followed that up with “…but should we be doing that?”  The team I was working with at the time probably could do just about anything.  But not everything can be done with a given budget and a specific deadline.  Some things are simply infeasible.

Scrum teams measure velocity – a reflection of how much software they deliver in a given iteration, as a function of how much work they believe is involved in delivering.  This is a great “protected” measure of efficiency.  The team is protected from requests to do work that has little or no value – by measuring throughput in terms of effort, a team can get more efficient at doing more.  A requirement is infeasible, and therefore unattainable, when it exceeds what the team can accomplish given a fixed amount of capacity.  Project managers refer to this as the Iron Triangle – given scope, cost, and quality, pick any two as inputs and the third will be a variable output (absorbing the impact of uncertainty that arises during the development process).  I prefer to use timeboxes rather than that rusty old triangle, to emphasize my perspective that quality is inherent in delivery, and should not be a “variable output of uncertainty.”  Because quality is what usually bears the brunt of uncertainty.

plus  yields

When the solution to a defined problem is prohibitively expensive, it is not attainable.  The notion of cost should also be considered in the context of value.  Requirements with higher value can justify implementing solutions with higher costs.

Prohibitively expensive solutions make requirements unattainable.  Relatively expensive (relative to their value) solutions also reflect unattainable requirements.  You need to collaborate with your implementation team to understand the costs associated with any particular requirement to know if it is attainable.  This is one of the strongest arguments against throw-it-over-the-wall interactions between product managers and implementation teams.  Without that feedback about feasibility and cost of a solution, you can’t assure that the requirements you are proposing are attainable.

Regular readers of Tyner Blain will realize that this is just an alternate way of stressing the importance of considering ROI when defining requirements.

Politics

There are political realities that every organization faces.  It could be a benevolent dictator CEO, or an executive with an agenda or pet project.  It may simply be that there is value in the problems you’ve identified, but solving them is not aligned with your corporate strategy.  You may be focusing on dominating an existing market, where expansion into new markets is the company’s focus – or vice versa.  You may be focusing on top-line growth opportunities, while the company is fixated on cost-reduction in a time of economic contraction.

Each of these scenarios causes you to be fighting an uphill battle internally.  When that hill is too steep, you’re writing unattainable requirements.

Process

When deciding what to build, you also have to think about how you launch.  Launching, as Dave Daniels regularly points out on his Launch Clinic blog, is not just putting your product up on your website for sale.  You have to think organizationally about all of the other moving parts:

• Do your customers have the ability to absorb an update to your software?
• Can your customer service reps be trained in time to promote and support the new capabilities?
• Will your sales team be able to communicate a message that helps them close deals based on what you’ve just built?

Process is more than just the process of typing, compiling, and testing code.  Process includes everything needed to successfully go to market and sustain your product.  If you’re defining requirements that are too far ahead of your market they are not attainable.  If your requirements embody process changes that are too difficult or expensive for your customers or your organization to absorb, your requirements are not attainable.

Conclusion

Attainable requirements are requirements that

• Have a reasonable cost to implement,
• Are aligned with your company’s strategy and stakeholder’s agendas, and
• Result in solutions that can be consumed by your company and your customers.

Make sure you’re writing attainable requirements.

Design-Free requirements are important for two reasons, and hard for two other reasons.

Design-free requirements are hard because you “know what you want” when you should be documenting “why you want it.”  Writing design-free requirements can be hard when you don’t trust your development team to “do the right thing” even though it is not your job to design the solution.

Design-Free Requirements – Revisiting

It has been three years since I wrote Writing Design-Free Requirements as part of The Big Ten Rules of Writing Requirements.  In that time, agile development practices have moved from being an esoteric development methodology to being the topic on the tips of everyone’s tongues as executives and organizations try to either (1) get the benefits of the state of the art in software-development process or (2) do something shiny and fashionable.

The previous article centered on elements of designs within MRD, PRD, and SRS artifacts.  A regular alphabet soup of artifacts.  Honoring the values behind the agile manifesto encourages us to emphasize working software over comprehensive documentation.  In that light, we’ll take a “what is needed” approach to talking about how requirements, design, and implementation are all needed – rather than issue an edict about where that information should be captured.

Agile Development Inputs

When creating software, someone needs to know:

• What problems are being solved, and how important (valuable) they are to be solved.
• Who has the problems and who is using the software to (help) solve those problems.
• What constraints limit the space that defines the universe of possible viable solutions.
• What acceptance criteria define if the delivered solution will be acceptable.

Subject to those inputs, someone needs to make design decisions:

• User experience design - what interactions will a user of our solution love?
• Program design – how (in a nuts and bolts way) will our solution function?

When talking about agile and talking about design, we should take a look at how Kent Beck and Alan Cooper, as respective though leaders in each space, view this.

Cooper doesn’t talk much about creating the requirements to support the daily use scenarios – he proposes moving directly into design of the solution. This differs from the more traditional technique of writing functional requirements to support use cases. Cooper also breaks down design into two components – program design and interaction design. Program design is everything you don’t see. Interaction design is everything you do see.

[...]

Cooper argues that designing the interaction should happen before any code is written. He uses a construction analogy to drive home his perspective – you can’t pour the concrete before you build the forms. Kent Beck, founder of the XP programming philosophy disagrees with the premise. Beck believes that the cost of changing software is low, and the imagery Cooper uses is hyperbole. We touch on, and link to that debate in this post.

Interaction Design Process Overview

I don’t believe that Beck is arguing for “don’t do design” – I believe he is arguing for “don’t do big upfront design that would delay implementation.”  He’s championing the agile values that emphasize creating working software and responding to change.  I can imagine him saying “no one will buy a design, they want a solution.”  Cooper’s point is that create a solution without first understanding how someone will use it, you can’t create a great product.

Program design has many hidden impacts – cost of maintenance, cost to change, and the performance of the solution.  You can have a design (or architecture) that makes everything easier to do in the future – at the cost of delaying the delivery of anything.  Or you can have a design that minimizes the time to deliver the first thing, while increasing the cost to deliver any particular next thing.  Or you can design a solution that falls somewhere between those extremes.

If you say “we don’t do design” you’re lying.  Every solution includes design.  Your team’s design process may be “big and upfront” or it could be a couple sketches on a whiteboard, or some email exchanges.  You may create storyboards and wireframes.  Or design may be the thing that happens right before the programmer’s fingers strike the keys.  Design may be explicit or it may be implicit – but it never “doesn’t happen.”

In the movie Amadeus, Salieri is astounded that there are no rough drafts of Mozart’s compositions.  That’s because Mozart did the design in his head, not because he didn’t do design.  I’ve worked with programmers who’s “implicit designs” were great, but that is the exception, not the rule.

Who Owns Design?

Since design happens sometime before fingers strike the keyboard, the real question is – “who owns the design?”

• You have a product manager developing an understanding of market problems, and prioritizing the problems that should be solved with your product.
• You may have a product owner managing the backlog and clarifying those requirements (problems) for the development team.
• You may have an interface (or interaction) designer or team of designers who are broadly responsible for “how users interact with our products.”
• You may have an architect or lead engineer who is responsible for the “big picture design” of how your product works.
• You have developers and testers who are responsible for delivering your product. [Note: coding without testing is like typing code without compiling - maybe it works, but probably not.]

You may not have distinct individuals with each of these titles – every small team I’ve worked with has people wearing multiple hats.  This is especially true when you have an agile team full of specializing generalists – any given story (or task) may have a different architect and different implementer.  I’ve only worked with one company where the architects are NOT part of the development team.  If your team is set up that way, please comment below – I had never seen that before, and I’m not convinced that it is the best way to organize – what have your experiences been?

Generally, “program design” is clearly owned by the development team – and product managers (and product owners) know better than to specify program design in their requirements.  Neither the lead engineer nor the product manager believes that the product manager is a better programmer – so the product manager better not be specifying program design and mislabeling it as requirements.  Coincidentally, Steve Johnson, at Pragmatic Marketing has a post running right now with a bit of a quiz – is this a req(uirment) or a spec (design)?

Where the line is more blurred is around interface and/or interaction design.  Some development teams have interface designers as part of the team.  Some companies organize with interface design as a “shared service” within the company.  Either approach can be the “right one” – it depends on too many details to make a sweeping generalization.  When the designers are members of the development team, the solution (from a product management perspective) is the same – the “team” is responsible for all design.  When the designers are not part of the development team, the developers have to consume two sets of guidance – “solve this problem” from product management, and “the solution needs to look like / act like this” from the designers.

Collaboration between product management and user experience people is the ideal solution.  The “requirements” and “design” inputs to the development team are comprehensive and consistent.

Design-Free Requirements

There are benefits – especially when being agile and minimizing documentation – to delivering requirements and design at the same time.  Just don’t do it by embedding design constraints within the requirements.

• When people on your team misinterpret design as requirements, they are unnecessarily constrained.
• As a product manager – are you the best designer on your team?  If you’re busy designing, who’s product managing?

This is trickiest when writing use cases – sequencing a set of interactions is interaction design.  That is one benefit of writing a user story instead of a use case.  An approach that has worked well for me with multiple teams is to deliver user stories (requirements) combined with storyboards (interaction design) and wireframes (interface design).  When details are needed (usually when “changing” versus “creating” an interface), screenshots can replace wireframes.  When business processes are complicated, process flows can replace storyboards.

Just don’t embed the designs within the requirements.

Kano Analysis, while initially created to understand customer satisfaction with features, can be used by product managers to better understand customer problems.  I gave a presentation last week for the Product Management View webinar series on Kano Analysis for product managers.

Kano Analysis – The Webinar

You can watch (flash) or listen to (mp3) the webinar (just under an hour) at the Product Management View webinar page for the Kano Analysis presentation.  I delivered the webinar on Sep 23rd, 2009.  Thanks Val Workman for inviting me to join the group and share an hour with a bunch of great folks.  Also, thanks to the people who asked questions, tweeted, and commented on the presentation.  I really appreciate it.

Kano Analysis – The Slides

If you want to flip through the slides to get a feel for the treatment I gave to Kano Analysis before committing an hour to the webinar, you can do so right here (or view the Kano Analysis slides on slideshare.net).

Thanks again to everyone, and if you have any feedback, include it below or on the PMV site.  Several links to other articles about Kano Analysis are in the comments on the PMV page, if you want to do further research.

Concise requirements give your team a useful, easy to read and easy to change understanding of what must be done.  Great requirements exist to do three things:

1. Identify the problems that need to be solved.
2. Explain why those problems are worth solving.
3. Define when those problems are solved.

Concise Requirements – Revisiting

In the three years since we last looked at Writing Concise Requirements from the Big Ten Rules of Writing Requirements, the iPod evolved to give us a better experience.  Let’s see if we can do the same with the topic of brevity in requirements.  The size of our community here has grown ten-fold, and the people who were here back then have grown just as much.  It makes sense to look at this again.

Writing concise requirements is not just minimizing the number of words you use.  Writing concise requirements is presenting the most important information in the easiest format for your audience to consume.

Concise Requirements Identify the Problems That Need to be Solved

Ultimately, requirements are the problems that we choose to solve.  A concise requirements artifact (formal document, index card, photo of a whiteboard, whatever) is one that has the highest signal-to-noise ratio possible.  You’re maximizing the amount of communication, and minimizing the cost of communicating.

You want your requirements document to read like the lines, not the points.  If the line (the signal) is what you really want, and you communicate a big pile of points (the signal, hidden in the noise), you run the very real risk that your audience will misinterpret the signal.

User stories provide the best example of clarity that comes from conciseness.  The format you should use, based on Mike Cohn’s great book, User Stories Applied, is

As a [role], I want to [do something] [with some frequency] so that I can/will [achieve some goal]

The user story is not always the right communication format – it depends on what problems you’re solving, and who is on your team.  Sometimes, use cases work better than user stories.  Conciseness is important for use cases too.  Start with a good use case name.

Concise Requirements Explain Why Those Problems Are Worth Solving

Last week’s article on Valuable Requirements focused on why particular problems should be solved.  Your focus should be on value, and that article discussed five ways to assure that your requirements are valuable.  One of the techniques, the use of an Ishikawa diagram, provides a method for identifying the root causes of problems.

[larger image]

Imagine that you have a collection of user stories, representing problems to be solved for your users.  You need a way to demonstrate why this user story should be implemented and why that one shouldn’t.  You can often use the Ishikawa diagram in the same way.  A particular goal is achieved when a user is able to do something.  Perhaps several somethings are required.  The point is that you can use the Ishikawa to drive home the point – if this set of user stories are all implemented, then this goal will be achieved.

There are two reasons this is important – first, you’re providing context for your team.  They understand why they are doing something.  Second, you can make changes easily, because you can see the impact of those changes.  By understanding the cause-and-effect relationships between problems and their values (user stories and their goals), you can see the impact of changing one or the other.

Concise Requirements Define When Those Problems Are Solved

Clarity is the goal of conciseness.  It isn’t enough to say “work on this.”  It’s important to know why you’re working on it, but that still isn’t enough.  You have to know when you’re done.  When you’re defining problems to be solved (and therefore solutions), you must also define the measures by which the solution will be judged.

A measurement of success for “Cost of Operation is Too High” might be “reduce costs of operation by 10%.”  This gives you a testable criteria for knowing when that problem has been sufficiently solved.  Sticking with the Ishikawa, you can also map out the strategy for achieving that lofty goal.  You can say that the goal is to reduce fuel expenses by 20%, reduce cost of maintenance by 5%, and reduce payments by 15%.  This process continues – a 20% reduction in fuel spend requires that you operate with your tires within 5% of nominal pressure, and that you reduce the aerodynamic drag coefficient by 7% (or whatever).

This gives you clarity in your objectives.

User stories, when combined with user acceptance criteria, provide that last connection of testability that lets your team know when they are done.

There aren’t many things more frustrating to a development team than having them solve the wrong problems.  One of those things might be having their solution be rejected because it isn’t enough.  Writing acceptance criteria clearly and concisely lets the team know exactly when they can move on to the next problem.

Providing a crisp understanding of acceptance criteria also facilitates iterative development.  One challenge teams always face is making improvements that fit within the timebox of a given iteration.  Imagine a user story with 4 acceptance criteria, where the story is too big to complete in one sprint.  When talking with your development team, you may find that the story is too big because satisfying all of the acceptance criteria is too big.  This is where many teams miss an opportunity – by defining all of the acceptance criteria that are believed to be needed eventually and requiring that they all be implemented now.  One of those criteria is going to be more important than the others.  Implement the story such that is satisfies the most important criteria (timeboxing) now, and rewrite or enhance it to meet the additional criteria later.

Conclusion

Software Product Success depends not only on identifying the “right stuff” to build, but on making sure the team builds it and builds it right.

Concise requirements improve your ability to communicate with your team, thereby improving their ability to build the right stuff right.

Writing valuable requirements is important.  It doesn’t matter how well your teams execute if they are off building the wrong products / capabilities / features.  The right products and capabilities are the ones that have relevant value.

• Valuable requirements solve problems in your market.
• Valuable requirements support your business strategy.
• Valuable requirements solve problems for your users.
• Valuable requirements meet your buyers’ criteria.
• Valuable requirements don’t over-solve the problems.

Valuable Requirements – Revisiting

A little over three years ago, I compiled the Big Ten Rules of Writing Good Requirements, which ended up with an even dozen “rules.”  The first rule was writing valuable requirements.  Three years is a long time.  Our environment has changed.  Many great insights have come into our neck of the software development woods from many inspired voices.  I’ve personally learned a lot.  My focus has changed from being more focused on product specification (back then) to being more engaged in business strategy (today).  Our audience here has grown ~ 10x since the original rules were published.  My dog has tripled in size.  Perhaps my writing has even improved.

Given that, it makes sense to revisit the topic now.

Valuable Requirements Solve Problems in your Market

I struggled a little about starting with “strategy” or starting with “the market.”  Pragmatic Marketing’s Framework (recently updated) starts with the market.  When I first watched the great video, where Jim Foxworthy introduces the updates to the grid, I was a little concerned about that.  Market first, strategy second.  Why not strategy first and market second?  I decided that I was happy with their presentation, since the framework is a tool for product managers.  Product managers usually have responsibility for a market, as a component of their company’s strategy – so the sequencing makes sense for a product manager audience.  Jim also puts it in perspective – their framework is focused on the company’s strategy for attacking a particular market.  I’ll stick with that here too.

To understand what problems are valuable for a particular market (or market segment) you have to approach it from your customer’s perspective.  What are the problems they are trying to solve?

Your customers might be distributors of retail products, who’s business it is to acquire, store, and redistribute small products.  They are in a business where their customers value accuracy, timeliness, and low cost of delivery.  Your customers may value solutions that allow them to more accurately redistribute products (they receive pallets full of items, and then redistribute them a case at a time).  They may value solutions that allow them to adapt to changes in orders with minimal turn-around time.  Or they may get the most value out of cost reductions.  Talk with your customers, listen to them talk about their problems.  When I was working for an enterprise software company years ago, our CEO stressed that he wanted to be solving the problems that keep our customer CEOs up at night.  Find out what those problems are.

The next challenge is in breaking those problems down into something actionable.  If your customers’ biggest problem is cost reduction, how do you solve it?  The first step is to understand where the costs are.  One way to visualize and decompose the problems your customers face is with an Ishikawa diagram (check this out to learn how to use an Ishikawa).

The following diagram shows a decomposition of “The cost of driving is too high” problem:

[larger image]

Now you’ve identified a set of problems that are valuable to your customers.  The Ishikawa can help you make sure you’re identifying problems, not the manifestations of problems.

You also have to understand what solutions are already available to your customers.  If you have a competitor that already offers a very good solution to one of the identified problems, your customers will find less value in a solution from you.

Valuable Requirements Support Your Business Strategy

With a set of problems in hand that are worth solving, you have to figure out which ones are aligned with your company’s strategy.

In the Ishikawa above, one of the problems that car owners face is excessively high payments (on their car loan).  Another problem is that the cost of maintenance is too high.  If your company provides financing products (loans and leases), trying to solve the cost of maintenance problem for your customers is probably out of alignment with your strategy.  Making the financing of a vehicle more affordable (while still profitable for your company) is probably a well-aligned problem.

Your company will also have a strategy for engaging the market – target market share levels, target market segments to penetrate, etc.  You may be trying to become a visionary company with your finger on the pulse of your market – or you may be trying to get mass adoption of your product by solving a very common problem, but solving it better than your competitors.  Your strategy for winning in this market may be to differentiate your offerings by solving different problems than your competitors, or defining a unique market.

Another way to think about alignment with your business strategy is to think about the owners of your company’s strategic goals – your internal stakeholders.  Most projects will fail (or be killed) without internal champions who believe in the ideas.

When you’re aligned with a part of your company strategy,  you’re aligned with whoever is the owner of that component of the strategy, and you’re providing value to that stakeholder.  Sometimes there are many components and stakeholders.  You can adapt some process-improvement prioritization techniques that Roger Burlton teaches to get an understanding of which goals are important to whom.

Valuable Requirements Solve Problems for Your Users

Products are used by people.  People use those products to accomplish goals.  They may be using your product for their employers, in which case they have “practical goals” (finish quickly) that represent how their company’s goals (lowered costs) are realized.  And those people usually interact with other people.  You can quickly build a visualization of who are the users (and indirect users).

[larger image]

You can think of this as an ecosystem of users of your product.  Develop personas and their goals to represent these users.  You can apply the same Ishikawa-based problem-decomposition technique when needed to make sure you’re uncovering the real problems (too many people abandon the sign-up process) and not the manifestations of those problems (users have to click too much).

When your users are not your customers, your users have personal and practical goals that represent their individual contributions to achieving your customer’s goals.  And your users achieve those goals by doing stuff.  You can represent that stuff with user stories or use cases.  The key element is to make sure that you’ve identified the valuable activities, the ones that are required to achieve goals.

[larger version]

The above diagram is used when assessing the completeness of requirements, which is an element of assuring valuable requirements.  If a goal has value, you have to identify the set of user stories required to achieve the goal.  Those user stories therefore have value.  User stories that don’t support a goal don’t have value.

Valuable Requirements Meet Your Buyer’s Criteria

The people who buy your products are sometimes not the people who use your products.  Even when the same person is both buyer and user, that person’s mental model for buying is different from their model for using a product.  If you can’t convince someone to buy your product, it doesn’t matter how great it would have been had they bought it.

Here are the opening soundbites from an earlier article on buyer personas.

• Buyer Persona: If you build what he thinks he wants, he’ll come.
• User Persona: If you build what he actually needs, he’ll come back.

And the closing summary points (it’s a long article):

• Buyer personas make purchases when products appear to address their internal view of what the problems are.
• User personas love products when those products solve the real problems.
• Don’t confuse buyers (who need to buy products to solve user problems) with users (who need to solve their own problems).
• When buyers and users are the same people, acknowledge the buyer-goals distinctly from the user-goals.

There are also several really great insights in the discussion thread – including great comments from Shaun Connolly, Edele Revella, and David Meerman Scott!

Valuable Requirements Don’t Over-Solve the Problems

More is better, right?  Not always.  Sometimes, “more” is a waste.  There are really two ways to think about how much is too much.

The ROI of Incremental Improvements

Because of the law of diminishing returns, the next “more” is always worth less than the previous “more.”  Think of it in terms of improving fuel-economy.  If you have a car that gets 10 mpg, and you drive 100 miles a day, you have to buy 10 gallons of gas a day.  If you improve the mpg by 10 mpg (to 20 mpg), you’ll save 5 gallons of gas per day.  Huge value.  If you improve the mpg by another 10 mpg (to 30 mpg), you’ll save an additional 1.3 gallons of gas per day.  Some value.  Another 10 mpg buys you 0.8 gallons per day.  Diminishing returns.

The cost of achieving “more” is also a factor.  The simplified diagram above shows a linear representation of cost as a black line.  The diminishing returns of value are represented as the red curve.  The optimal investment point is where the two curves are tangent (have the same slope) – marked with the blue circle.  Less investment leaves money on the table – additional investment is done at a loss.

Good Enough is Enough

You don’t need to super-solve the problem.  How much more would you pay for a car that got 10,000 mpg than one that got 1,000 mpg?  If you drove 100 miles a day, the difference between the two (from a value standpoint) is trivial.  Over the course of 100 days, you would save 9 gallons total with the car that had ten times the fuel efficiency.

Why haven’t microwave ovens been getting faster every year? Because the move from a 1-hr baked potato to a 5-minute baked potato is good enough.  You don’t need to get it under 4 minutes.

This is known as satisficing - stopping when something is good, not trying to make it “perfect.”  Additional “goodness” will not result in enough additional sales to justify the investment.

Conclusion

The tagline for Tyner Blain is Software Product Success.  On an elevator, I explain that you have to not only “build stuff right” but you have to “build the right stuff.”  And the right stuff is the valuable stuff.

Define valuable requirements to make sure you’re building the right stuff.

User stories can make requirements management a lot easier.  They shift some of the communication from up-front documentation to ongoing dialog.  That’s the main reason they work so well for agile teams.  And agile teams focus on “what’s next?” instead of an ever-changing “what’s everything?”   The problem is, when those conversations are working well, it is easy to forget to make sure that what you’ve done is actually enough.  Add a small dose of traceability, and you can easily validate the completeness of your user stories.

Three Big User Story Problems

Over the last few years, Alistair Cockburn surveyed a range of teams and identified that they all were facing a similar set of problems.  Alistair proposed using use cases to solve those problems.  The following list of problems is Alistair’s:

1. Designers lack the context of the goal that the user is trying to achieve.
2. The team does not get a early indication of the scope of the project.
3. Alternate user-behaviors are not identified in advance of the commitment to deliver.

We agreed then (and still do) that well developed use cases can be used to address these issues.  Since then, however, we’ve done more analysis of how and when to create use cases and when to create user stories.  The primary drivers of the use case versus user story decision still apply, and should still sometimes point you to creating user stories.

Without the context of goals, and without a notion of completeness, your team just has a haphazhard stack of stories.  Not only will this reduce their motivation, but it will introduce frustration both for the implementation team and the stakeholders – no one will really know when the job is done.  Validating the completness of user stories will allow you to know (and regularly revisit) when you should be done.

When you are creating user stories, you need to be able to address the issues Cockburn identified.  You can do that with traceability, and a very small amount of additional documentation.

User Story Metadata

The cool thing about a well-written user story is that it already has metadata within it that makes tracing very easy.  A well-written user story, using a format based on the work of Mike Cohn (in User Stories Applied), would read:

As a [role], I want to [do something] [with some frequency] so that I can/will [achieve some goal].

If you were to build a UML Class Diagram to show the relationships that are implicit in a user story, you would get something that looks like the following:

[larger version]

• The [role] that starts a user story is the persona (lower right corner of the diagram).  For products with simple market strategies, identification of personas alone is sufficient.  Larger companies and larger products are often trying to address the needs of users in multiple markets or market segments.  Each persona you develop is in a single market segment.  You may organize your segments regionally or by vertical industry or any other strategy that helps you position your product.  You can manage your personas not only as members of market segments, but with a hierarchy of roles.
• The [do something] you identify is the meat of the user story (top center of the diagram) – what the persona is going to do.
• The [with some frequency] element tells your team how often a particular user story will happen.  This can be represented as an attribute of the user story.
• The [achieve some goal] component of the user story provides the context (center of diagram) for why a user will be performing an action.  The user will be performing the action either to achieve a user goal or a corporate goal.  If it is a corporate goal, it will have an internal stakeholder.  Ultimately, there should be an internal stakeholder who is not only the beneficiary of that goal, but also the person who “owns” the market segment in which the persona is defined.  Sometimes, there will be conflicts in goals, commonly between user and corporate goals.  These can also result in conflicting goals between internal stakeholders.

This is what makes things pretty exciting – all of that information is already there, and in your user story.  All you have to do now is leverage it.

Goals and User Stories

The following diagram shows how a use case exists to enable the achievement of a goal.

A user story can exist in the same way, just replacing the use case.  If you want to do a deeper dive into how interaction design and structured requirements work together, you can use the following model instead:

Note that the diagram above introduces a couple additional concepts.  The first additional concept is the practical goal – what the persona is attempting to do because it is the manifestation of a corporate goal.  ”Take an order quickly” is the practical goal that manifests the corporate goal of “Reduce time required to take orders.”  The second concept is that of a scenario.  A scenario is an amalgam of user stories (or use cases) that collectively allow the persona to achieve the practical goal.  We already represent this without introducing the scenario concept by acknowledging that a single goal is mapped to multiple user stories.

The common element in both approaches is a strong tie between goals and user stories.  Focusing on this aspect, you can visualize the relationship as follows:

[larger version]

Note that the acceptance criteria for each user story are called out (so that you can confirm that a user story is “done” and “done well”).  Each goal is achieved by enabling one or more user stories, such that the acceptance criteria are met.  This is the crux of it, so I’ll write it again, but in bold for the busy people who scan this article.

Each goal is achieved by enabling one or more user stories, such that the acceptance criteria are met.

Note also that multiple goals can be supported by the same user story.

Validating Completeness

The important question that many developers (agile or otherwise) can not answer about their project is “If we do [everything we've been asked to do] will we meet our goals?”  This is either a failure in communication of context, or a failure to validate completeness of the requirements.  You have to flip things around and ask “If only these user stories are implemented, will the goal(s) be achieved?”  This is the same process used to validate completeness of use cases – just applied to user stories [Ed: that completeness-validation article was written 3 years ago today.  That's 28 years ago in internet time].

Incremental Overhead

Each user story already identifies the goal(s) it is supporting.  The incremental overhead is to recognize that this is “a backwards view” of goal satisfaction and create a simple table that shows the “forward view.”

You are creating traceability from each goal to each of its supporting user stories – but you’re doing it with a simple table (or list, or tree, or whatever).  You don’t have to manage your requirements in some big messy repository.  If you’re using index cards, consider getting some brightly colored sticky-dots, number them for each goal, and stick them on the index cards to show the relationship.

Then ask the question, for each goal, “Will this goal be achieved if all of the traced user stories (and no other stories) are completed, such that the acceptance criteria are met?”

An added benefit of this simple document is that it markedly improves your engagement with internal stakeholders.  You’ve created another opportunity for them to influence the scope of delivery.  These stakeholders can identify user stories that don’t map to any goals (you can drop those stories), and by identifying incomplete support, you can collaborate to make sure the missing user stories are identified.

The task of updating stakeholders about progress and managing stakeholder expectations just got much easier – because you can report progress in the context of completed user stories (and therefore manifested goals).

Reviewing Cockburn’s Issues

Does this approach address Cockburn’s issues (listed at the start of this article)?

1. Lacking the context of goals.  This approach explicitly emphasizes that context.
2. No early indication of scope.  The combination of completeness analysis and acceptance criteria provides concrete insight about scope.  Note that scope can still change, but this approach is just as effective as documenting requirements with use cases.
3. Alternate behaviors not identified early.  Completeness analysis will highlight when the “happy path” (a.k.a. the normal course in a use case) is not sufficient to achieve the goal.  This is really just a variation of the second issue (not understanding scope), but along a variation dimension instead of a coverage dimension.

Conclusion

There is value in being able to document requirements with either user stories or use cases as circumstances dictate.  Cockburn identified issues that teams face when dealing with decoupled user stories.  His approach of leveraging use cases to solve the issues is perfectly valid.  The approach outlined above, tracing user stories, also addresses the issues.  As a product manager or business analyst, you need to be able to address the very real issues with either documentation approach.

Jump forward in time to the day of your next big product launch (first release, new features, new market segment, etc).  And your site/application crashes due to the “unexpected” demand.  All you can do now is look for a bucket of water to put out the fire.  What could you have done to prevent this disaster?  Jump back to today and start doing it!

Backwards Planning

Depending on how you look at things, this is a backwards planning exercise, or a variation of the  remember the future innovation game, or risk management, or proactive product management.  You can avoid a disaster by imagining what might happen, then hypothetically figuring out why it (would have) happened.  That leads to planning how you could prevent it.  And now you’ve left the dream world of a Gedanken experiment and returned to the real world of product management.

Problem Triage

The way to approach this is straightforward.  Imagine some failure scenarios and the importance of preventing them:

1. Imagine a failure scenario.
2. “Predict” the likelihood of the failure.
3. “Estimate the impact of the failure.
4. Repeat for each scenario

You can prioritize your failure scenarios by multiplying the likelihood of each with the impact of each, and sorting them from largest to smallest.  Then determine which ones you’re willing to address, and which ones you’re willing to risk.  You may not be able to predict the likelihood of some failures (at least until you do a root cause analysis).  Take each of these and put them directly above the scenario with the next highest impact.  The rationalle is that these are so bad, that you really want to find out how likely they are to happen.  Once you predict likelihood (see below) you can reprioritize.

Root Cause Analysis

For the failure scenarios you choose to address, the next step is to do a root cause analysis that identifies why it might have happened.  The best tool for capturing this analysis is an Ishikawa diagram.  Consider that one problem you might face is your website crashing.

[click for larger version]

Essentially, you can crash your site by having too many users, too many concurrent users, or too many concurrent sign-ups.  Developing a cause-and-effect diagram (another name for an Ishikawa diagram) is usually an iterative and exploratory process.  You probably won’t create the simple version above first.  You may ask your implementation team “What can cause the website to crash?”  For each of their answers, you identify when that situation can happen.  Or you start top down.  Most likely, a mix of the two.  Your completed root cause analysis may look like the following:

[click for larger version]

At this point, your team can probably predict many (maybe all) of the root causes of a website crash.  The predictions may be conditional – “we can handle 10 concurrent users, but 20 probably kill us, and 100 definitely would.”  Developers are notoriously good at answering questions with conditional statements that reveal the nuances of their thinking.

Remember that you’re looking back from the future.  At product launch, what are you hoping for / reasonably expecting?  For this example, assume it is 10,000 total users, with 100 concurrent users (normally) and 500 concurrent signups.  You determine these numbers by working with your PR, marketing, or mar-com people (or wearing those hats, when it is all you).  Your plan is to do a big launch with a demo and a promo code for signup.  You know your audience will have internet connections, and will have twitter running at the time of your presentation.  You expect/dream of an immediate burst of signups, followed by tweets and word of mouth, and eventually blog articles causing additional growth over the next couple of weeks.

Use this data to feed back into the developer’s conditional responses.  If you’re like me, you will have found “absolute certainty of failure” from something.  And you may have even identified the thresholds for each element.  For example, database loading can handle 75 concurrent users, but with the current implementation, you only have enough database connections available to support 25 concurrent users.

Jumping back to the present, you now have some very discrete, and very important things to do before your launch.  If you need to, revisit the prioritized list of failure scenarios.  By looking at the next level of detail, have you found that the order of importance (to fix) has changed?  What about the “must fix” versus “willing to risk” line?  Has it moved?

Fold the “must fix” items into your backlog, and prioritize them relative to the other capabilities on your roadmap.  As a side note – make sure you’ve built in some testing to make sure you actually prevent the problems.  This might even be a great opportunity to implement “performance regression tests” – it is not enough to prevent bugs, you have to prevent slowdowns.

Rethinking the Problem

Without going into details on how the team will solve each problem, make sure that together you keep the Ishikawa diagrams in mind, and see how any proposed solutions might “reappear” on the diagram.  For example, rewriting your database connections to use asynchronous processes and a set of pooled connections may prevent a crash, but it may really hurt performance.  You may not have time to find an elegant solution.  So stop and rethink the problem.

At this point, you’ve said

1. Given a marketing plan / launch strategy, we would crash the website.
2. We can make changes between now and the launch that will double the number of concurrent users we can support (or whatever), but that is not enough to support the launch strategy.
3. Solution: Change the launch strategy.

Maybe you can’t support a wide-open promo-code based signup.  You should modify your launch so that it can only create as much demand as your product (including pending improvements) can support.  Maybe you limit it to the first 1,000 new users (probably more code to write to enforce the limit).  Maybe you launch with per-user invitations, where you can control the speed of propagation of invites (start with 100, when those have been sent, make another 100 available, etc).

Entire Team Problem

This is a problem that is solved collaboratively, by the entire team.  It is not just a “go write the code” problem.  What your product can support at a launch should drive how you choose to launch, just as how you choose to launch should drive what you want your product to support.  

You may have to delay a key capability in order to scale.  Does your marketing team know this?  Slightly less bad than crashing would be announcing a feature that is disabled.  Still need to announce the feature?  Pre-announce it: “Coming in a month…”

This stuff is important for every company and product, but it is especially critical for start-ups.  As a start-up, you have limited opportunities to grow, and a limited safety-net to catch you when you fail to capitalize on those opportunities.  So make sure everyone (not just the development team) is aligned to make the best use of each opportunity.

Conclusion

You have an opportunity to prevent problems.  All you have to do is imagine that they have happened in the future, figure out why they would have happened, then do what it takes (in software, or organizationally) to prevent them.

Just because your requirement is not a user story does not mean you have to throw it out when planning your next sprint.  See one way (that is working) for managing non-functional requirements with an agile team.

Product Backlog Stories

Every article* I can remember reading that explains how to manage a product backlog talks about user stories.  Those articles are necessary, but not sufficient .  You’ll create better products by developing them from the outside-in, with a user-centric point of view.

*One loophole – scheduling refactoring (or the payback of technical debt).  A lot of articles talk about the need to do this, and refactoring is pretty much the opposite of a user story, since by definition, refactoring improves the software without introducing new capabilities.  The best idea I’ve come across for incorporating refactoring as part of a sprint is to write a user story, with the system as the user, and the lead architect / developer as the primary stakeholder.  This actually works really well, but it works by treating the work as a user story.

Atomicity

What is really important, when scheduling sprints (or releases, if you are not doing scrum) is that you are scheduling solutions to atomic, measureable, valuable problems.  Atomicity is the reason for breaking epics (really big stories) up into smaller stories.  It is also important that you communicate them unambiguously.  That might mean writing user stories or writing use cases instead of user stories, when things are complicated.

The problem is, not every atomic requirement can be represented with a user story.  Some things that must be, are not stories.

Non-Functional Requirements

Non-functional requirements always seem to be under-emphasized when writing requirements.  The Twitter fail whale has become famous, because twitter could not scale to meet the demands of a rapidly growing user base.  Maybe the Twitter team planned for scalability, but demand simply outstripped it.  Or maybe they failed to plan for it.  Either way, they failed to meet the non-functional requirements of supporting the growth that they did have.  (Un)Luckily, this type of problem self-corrects.  Scaling failures drive away users, reducing the need to scale, until balance is achieved.

Product managers and business analysts tend to neglect non-functional requirements.  Unfortunately, this is especially true when managing with a focus on users and their goals.  Not because goals don’t drive non-functional requirements – they do.  I believe this has happened because historically, non-functional requirements were treated as an after-thought.  In reality, they are explicitly driven by goals.  I proposed an equal rights amendment to the structured requirements domain model almost three years ago.  In short, it explicitly calls out the relationship between goals and non-functional requirements.

Agile Non-Functional Requirements

Getting non-functional requirements into your sprint planning is actually not that hard.  You only have to make two tiny adjustments to get from the waterfall world to the agile world.

The first adjusment is that you have to treat non-functional requirements incrementally.  Non-functional requirements often affect all of the other requirements – so they seem massive and unweildy.  You have to decompose them.  Consider the platform-compatibility requirements for a web application.  You may have to support IE6,7,8; Safari on Windows, Safari on OS X, and Firefox on Windows XP and Vista.  That could be incredibly daunting.  So break it down.  Your first group of users (key persona) are primarily Firefox/XP users.  So the first platform you support is that one.  The next big platform for your persona group is Safari on OS X.  Add support for that next without breaking the previous support for FF/XP.  With each release, you add a platform (or two, or none).  You are conspicuoulsy addressing the needs of your target users.  The key is that once support is added for a platform, all future development is required to “not break it.”

Each non-functional requirement is cumulative.  This is the second adjustment.  All development, once a non-functional requirement is in place, must continue to honor it.  You wouldn’t break a previously released capability (functional requirement), so don’t break a non-functional requirement.  You have to determine, in each sprint, if additional functionality is more important than additional platform support.  And add in the platforms as they become the most important “next things to do.”  In waterfall projects, I’ve seen many teams break and re-break platform support throughout the development process, with the knowledge that it only has to work “at the end.”  Include platform-specific support in your continuous integration tests.

You have a launch event coming up in six weeks.  You have an established user base.  You’re also developing a key new set of capabilities for your product that you believe will be a big hit and drive significant growth for your product.  You have a small group of people in a private beta, providing you with feedback about the new development.  If you believe the launch will cause your customer base to double very quickly (maybe over a month), how do you plan for that?  This is a serious scalability non-functional requirement.

Break the non-functional requirement up into cumulative requirements.  Assuming your plan is to add 10,000 users “at once” – have your implementation team brainstorm what that could/would mean for the system.  [Also, make sure you coordinate with your community manager and marketing folks, both to validate the anticipated growth, and to device any contingency strategies in advance.]  After talking with your development team, perhaps you learn that “at once” is a nuanced proposition.  Literally at once is very bad.  Spread out over a few days, not so bad.  OK – you can deal with this too.

Imagine you already have the following non-functional requirements in place:

• The system must be available 24/7, with no more than one hour of down time per day, and no more than one outage per day.
• The system must respond in under 2 seconds for >95% of uses [ in key user story].
• The system must respond in under 20 seconds for 100% of uses [in same key user story].

Based on what we’ve said above, these non-functional requirements must not be broken.  They essentially define the acceptance criteria for our scalability requirements.

Consider the following as the non-functional requirements that must be deployed by the time of launch (six weeks, or three releases from now):

• The system must support 10,000 additional users added in the month following SXSW.
• The system must support 500 new users signing up and initiating [troublesome user story] within the same hour.

Your dev team does not really know exactly what needs to be done – they just know that the current solution won’t scale – it barely meets the existing non-functional requirements.  They propose a couple redesigns that may get the job done.  But they point out the need to actually test that the designs work.  Schedule the following for the first release:

• The system must support 100 additional private beta users.
• The additional users will all have [troublesome user story] initiated within the same hour.

The second one is really a pragmatic solution – artificially creating a spike in demand, to test out the scalability of the new code.  From that data, we can determine what we need to do to hit 10,000 additional users, and to support 500 concurrent [troublesome user story] instances.  By managing expectations of the new users (that you’re queuing them up to test scalability), you can get the data you need.  And you have a couple more iterations to improve if needed.

As a benefit, you get to completely avoid the fail whale.  The other half of this is making sure you can constrain the rate of new-user sign-ups.  Work with your community manager and marketer to make sure you position this effectively.  You are creating scarcity, which may increase demand.  A crashed server won’t.  If your team can’t support 10,000 in time for the launch, plan on 2,500.

Conclusion

You can plan and schedule more than just user stories.  And your product will be better for it.  Give those non-functional requirements a chance.

User Stories are one of the key agile artifacts for helping implementation teams deliver the most important capabilities first.  They differ from use cases in some important ways, but share more commonalities than you might think.

User Stories Applied

Mike Cohn wrote User Stories Applied: For Agile Software Development.  It is the book for understanding how to write, estimate, and use user stories.  If you’re thinking about trying out “agile” for the first time – and you haven’t read his book, you need to.  He provides great detail and anecdotes about how to write, manage, and utilize user stories.

What are user stories?

A user story is a user-centric description of the goals that one or more people will achieve by using your product.  User stories are applicable whenever there is a person, interacting with an interface to a product, to achieve a goal.  They aren’t just for software – even though the tone of this article may imply it (since I live in a software mindset most of the time).

A user story is written in the format

• As a [person in a role] I want to [perform some activity] so that [some goal is achieved].

That’s it.  No more.  Perfectly atomic, very concise and unambiguous.  Where did this elegant idea come from?

User-centered design (UCD) is an approach to product design that can almost be considered a philosophy.  In college, I used to say that industrial designers designed things from the outside in, and engineers designed things from the inside out.  The ideal products are the ones that marry form (outside) and function (inside) in an elegant solution that blurs the lines of distinction.  The first designers of engineered products were the engineers, and the first designers of software were the programmers – they were the only ones who knew what could be accomplished.  Anyone who has used an application with a user interface designed by a database expert can remember what that was like.  Eventually, someone successfully adopted the mindset of designing a product based on what someone could use it to do instead of looking at what it could do and figuring out how to use it.  That under-emphasizes the importance of UCD, but you get the idea.

Out of UCD come different things that really drive how we create products today.  Kessler and Sweitzer focus on understanding these user goals in Outside-In Software Development.  Stakeholder goals drive (arguably, are) requirements.  But it is difficult to develop actionable implementation plans directly from goals.  You need something to bridge that gap.

A user story, in an agile process, bridges that gap.  In Wiegers’ world of structured requirements, that gap is spanned with use cases.

Conceptually, a user story crosses the same chasm as a use case.  A user story defines what people need to accomplish (e.g. faster call processing), in order to achieve the goals of the company (e.g. lower call-center costs), given a solution approach (write software versus outsource to lower-cost call center employees).

Now we find ourselves in a confusing situation – there are user stories, use case scenarios, and at least three different kinds of use cases – formal and informal use cases, and use case briefs.  How are they different, and how are they the same?

Usage Descriptors

Use cases, use case scenarios, and user stories all document descriptions of how a product will be used.  They vary, along a continuum, in terms of the amount of overhead required to create each.

• Formal use cases require the most effort.  They have a lot of pomp and circumstance going on, but they describe all the permutations of how some person does some activity (or its variations).
• Informal use cases are pretty much the same – just less formal.  The challenge is to provide the right level of detail, without the guide-rails of the formal use case to remind you.
• Use case briefs have almost no overhead, but have the same “how much is enough” challenges of informal use cases, only more so.  Think of it as a single-paragraph description of a formal use case.
• User stories have the least overhead, and provide the least context.

Use case scenarios are a slightly different breed.  Like a user story, a use case scenario describes one path through a multi-path use case.  But you can’t (or at least I’ve never seen anyone) create a use case scenario without first creating the formal use cases.  This artifact basically combines the weakness of a formal use case (high overhead) with that of a user story (limited context).  It can be very handy for developing test cases if your testing team is not well versed in writing test cases.  We’ll leave use case scenarios out of the rest of the discussion.

The cost of high overhead in documentation comes with a benefit – increased detail.

Because a user story captures a single path through a use case, while having less overhead, it also captures less detail.  This is ok, because an agile process stresses communication over comprehensive documentation.   You start to run into inefficiencies when the amount of conversation (especially when repeated) is burdensome.  The amount of conversation required is a function of the amount of domain expertise, or context, that the implementation team already has.

Should I write User Stories or Use Cases?

It depends on your audience.  The formal and informal use cases, in addition to having more overhead, also provide more context, and allow you to describe more complex usage patterns of your product.  Some uses are so complicated that you have to use a use case to describe them.  Others are so simple that anything other than a story is wasted effort.  The interpretation of complicated and simple, though, is not purely an assessment of what the users want to do – it varies with the level of domain expertise of your implementation team.

Some teams simply aren’t equipped to consume user stories or use case briefs.  You have to write your requirements for the readers, so you need to know when people are struggling to implement solutions based upon stories or briefs, and give them more structure and formality.  You have to adapt to the realities of your current situation, and the experience of your team.

You could replace the words “Reader Domain Expertise” with “Writer Trust of the Team” if you wanted, and the graph would look about the same.  This is another concept that is critical to a team working effectively – trust equates to delegation.

If you can trust your team to come up with a solution that matches the story, delegate that “next level of detail” to them.  If you can’t trust them, then don’t.  But you should.  One of the benefits of agile is that your team will quickly give you a solution, and then you can give them feedback.  If they don’t create a solution that meets your interpretation of your user’s needs, then give them feedback, and they will change it.  The agile process actually relies on this dynamic to allow less-verbose artifacts to still be effective.  Someone on the team will sketch out what the solution will look like, and get your feedback, before implementing.  The more this collaboration happens, the more effective a light-weight document will be.

Conclusion

Don’t just rely on platitudes about stories and use cases.  Think about the nature of the different artifacts.  Think about their strengths and weaknesses.  Consider how you interact with your team.  Should you trust your team?  Do you trust your team?  Determine what they need, and give it to them.

Agile development methodologies succeed because they help development teams be as effective as possible.  Development teams do not, however, work in complete isolation.  The company they work for has a strategy.  The company manages a portfolio of products, and targets a particular product at specific market problems.  Within that context, an agile team can thrive.  What’s the best way to provide that context?

Agile Development in Context

Mike Cohn of Mountain Goat Software gave a presentation to the bayXP group in March 2007 on agile estimation and planning (video and pdf at link).  As part of setting the stage for his planning presentation, he describes the software development ecosystem as an onion.  So did I, coincidentally, in 2006.  The gist of both onions is that software development is implementation, in the context of design, driven by requirements, formed to address market opportunities.  Mike’s onion provides specific insights into the execution approach of an agile team, so let’s frame this conversation using his terms (but a new visual).

• A company has a strategy.  [Example: "Organize the world's information..."]
• A company has a portfolio of products that is intended to provide a mechanism by which the company can achieve its strategy.  [Example: Gmail, Chrome, Gears, Reader, Docs, etc.]
• Each product (or service) the company creates is an intentional part of the portfolio, targeted at specific markets or market segments, with an intention to solve specific problems.  [Example: Gears allows people to consume online content when offline.]
• A product is delivered through a series of releases. [Example: Chrome release 0.2.149.30.]
• The work that goes into a release, when practicing incremental development, may be decomposed into multiple iterations.  [Example: Chrome iteration 0.2.149.29, not released, but built and tested]
• In scrum, the completion of tasks within an iteration are managed daily.  [Example: Today, I will add the 'check for updates' to the 'About Chrome' popup.]

Many people talk about the agile process as if it encompassed the entire perspective shown above.  It doesn’t.  When you talk about the software development lifecycle from the strategy level down, you’re really talking about business strategy.  Agile development happens in the context of a business strategy, a product portfolio designed to achieve those strategic goals, and the product in that portfolio that is being developed.

Saeed Khan puts it pretty well in his first article about agile / scrum:

Keep in mind, Agile/Scrum is a DEVELOPMENT methodology. It is a great model for developers and engineers and other R&D team members to work and communicate more efficiently. There are very clear benefits to this model. It provides greater visibility into current work status, work remaining, can identify development hurdles earlier and can communicate them outward more easily.

I agree with Saeed.  In the diagram above, the layers that represent “what we do” have black text and borders (Strategy, Portfolio, and Product).  The layers that represent “how we do it” have white text and borders (Release, Iteration, Daily).  In Mike Cohn’s presentation on agile planning, he specifically calls out that agile planning happens in this (inner) scope.

Managing a product backlog (in scrum) is the place where things blur a little.  Determining what goes into the product backlog is “what we do”, prioritizing those product backlog items is “when do we do it”, and fitting them into individual releases (timeboxes and rolling-wave planning) is “how we do it.”  As agile teams stress, communication here is the key.

The true challenge that companies face is to provide agile development teams with the context needed to develop software.

Providing Context to Agile Teams

Product management is primarily a strategic activity, combining market insights () with company strategy to design a product portfolio, and to determine which problems a particular product should solve, for a particular market segment.  This leads to a focus on buyer personas and user personas.

Establishing and maintaining the connection between market insights and agile development teams will develop a distinctive competence for your company.  One key is to connect stakeholder goals with implementation activities.  This involves translation from the language of business to the language of developers.

An effective bridge across that communication divide has to be visceral and very straightforward.  Many agile team members rail against anything that looks like overhead, and the manifesto even codifies this disposition – “working software over comprehensive documentation.”

Our magic decoder ring must be simple, explicit, and light-weight.  Sounds like a job for the Ishikawa diagram.

Ishikawa Diagrams for Agile Product Management

The Ishikawa diagram, also known as a cause-and-effect diagram or as a fishbone diagram, can be used to describe and decompose market problems.  Consider the following near-real-world example:

You’re developing a product for sales reps.  The key to your product’s success is user adoption, and you believe the way to get that adoption is by helping sales reps to maximize their compensation.  Sales reps are generally managed via commission-based compensation models.  You establish “Maximize Sales Compensation” as a goal for your software (for these users, in this market segment).  You then acknowledge that there are a series of “smaller” problems that have to be solved before sales reps actually can maximize their compensation.  An Ishikawa diagram of your results would look like the following (consider only the main branches):

[click for larger version]

For some problems (and some teams!) this may be enough information to provide the context to develop a product backlog.  And your agile team will move forward into managing their own execution from the product backlog stage.  For larger or more complex problems (such as this example), you will need more detailed communication before diving into user stories / use cases.

The same Ishikawa diagram, with more detail, looks like the following:

[click for larger version]

For the largest and most complex problems, this is still not enough.  You can take each major branch of the Ishikawa diagram and create a child Ishikawa diagram.  However, from an agile standpoint (as in “staying close to your market”), you don’t want to do all of that detailed analysis up front.  Once you’ve prioritized the main branches in your main Ishikawa diagram, you will want to go to the next level of detail only for the first branch.  You want to make sure that you are delivering “working software” – not “comprehensive documentation.”  Delay your detailed analysis to the last practical moment.

Assuming you chose “Improve Predictability of Sales” as the first market problem to address with your product.  And within that choice, you are going to tackle “Align Solutions to Customer Problems” first.  Your child Ishikawa diagram could look like the following:

[click for larger version]

At this point, you would start writing user stories (or defining use cases) around recording customer problems, searching for ‘comparable problems’, predicting the problems a customer might face (before your first sales call), etc.  Those user stories will then get mapped to releases and iterations, and their implementation will be managed through the daily standups.

Outbound Communication of Agile Delivery

This problem-decomposition approach was presented top-down, specifically around providing the needed context to an agile development team to guide their design and implementation activities, giving them the opportunity to intentionally solve valuable problems, in alignment with the company’s strategy.

This same approach can be leveraged in outbound communication of what the team will deliver (and when).  You can easily construct a product roadmap that is actually an “agile problem roadmap.” [Ed: can I trademark that?  Probably not, since Enthiosys already does it, but without the word problem.]  In the short term, talk about specific problems (“Align Solutions to Customer Problems”) that you are solving.  In the longer range plan, talk about the next level of problems (“Improve Predictability of Sales”).  The team is not committing to a widget or feature.  The team is committing to providing a solution to a particular problem in a given release.

When you commit to a particular feature, you inhibit your ability to change as you learn.  And that’s bad.  You need to be able (after each iteration) to say “This problem is still valuable, but our previous idea about how to solve it turned out to be a bad idea.”  If you communicate at the feature level, you’ve added overhead to your process – you now have to manage expectations and update your communications, EVERY time you change designs.

You introduce another problem – these Ishikawa diagrams are so easy to read, and you’re now managing your roadmap based on problems being solved in a given iteration/release – should you tell everyone?  Many product managers sidestep the “Do we make our roadmap public?” question because they don’t create an easy to consume roadmap.  With this approach, you do.  So you have to decide if it needs to be a secret.

Zero-Overhead Planning

Early in this article, I said “agile team members rail against anything that looks like overhead.”  Creating Ishikawa diagrams is zero-overhead.  Or nearly so.  99% of the work that is displayed through the Ishikawa is work that you have to do anyway, to have an intentional approach to product creation.  The only overhead that is introduced is in the creation of the Ishikawa diagram.  If your thoughts aren’t already organized this way, you’re in trouble.  It takes almost no time to create the diagram that reflects what you should already be thinking.

And that qualifies as low-overhead.  And high value.  That should win over any resistance from the team.

Conclusion

As a product manager, you have to synthesize market problems, and develop a product vision to solve those problems that is aligned with your strategy.  As someone who is “part of” or “working with” (whichever matches your situation) an agile development team, you need a way to provide context to your implementation team.  That context can easily be conveyed with an Ishikawa diagram, with almost no incremental effort.  Your team can easily consume the diagram, and it gives them the freedom to explore different solution designs.  It also enables you to communicate your plans with the rest of the company (and externally, if desired).

Jun 14th was the first productcamp in Austin (and the second one anywhere).  It was a great event, and here’s the presentation that I did on how to define the strategic problems that drive our products.

Defining Problems

Here’s the presentation I gave at ProductCampAustin 1, posted on slideshare.  Just click on the forward/back arrows in the center of the bottom of the image, and it will cycle through the presentation – you don’t even have to leave Tyner Blain.

| View | Upload your own

Following Along

In keeping with the “don’t put a lot of words on your slides” tradition, the presentation is probably all but impossible to follow without some notes.  So here are some notes, organized by slide.  The presentation builds on concepts we’ve talked about here over the years, and in the notes below, I’ll link to some of those previous articles to provide more depth (instead of typing out everything I said).

• Slide 1.  There are two key elements to achieving software product success.  Build the right stuff, and build it right.  This presentation is about building the right stuff.
• Slide 2.  Specifically, when we start a project, it is to achieve some business objective.  The challenge is to find the right level of abstraction for that objective.  “Increase shareholder value” is too nebulous, and “Replace a legacy system” is too lacking in context.  Today we will apply a very powerful, but simple technique to help define the business objectives at the right level of detail to be actionable, while providing the right context to validate that we’re doing the right thing. My goal is for everyone to leave here with a new skill that they can immediately apply.
• Slide 3.  Everyone has a different perspective on a software project, and from those vantage points, perceives different elements of the project as the “why, what, and how” of the project.
• Slide 4.  Keeping in mind that people have different perspectives, let’s also look at a modified version of Karl Wiegers’ structured approach to requirements definition.
• Slide 5.  Introducing the Ishikawa diagram.
• Slide 6.  Set up the “deflated tires” problem from the article linked in (slide 5).
• Slide 7.  Showed the discovery process and representation of “real problems” closing out the theme from slides 5 and 6.
• Slide 8.  A real-world project I joined mid-stream for a client.  The project was a “collection of stuff” and no two people would give the same answer for “why are we doing it” and many people unashamedly admitted that they had no idea why.  No idea why!
• Slide 9.  Turns out, here’s what a view of the value for that program really looked like.  The team went from chaos to context.  Suddenly, scope discussions and prioritization decisions had a framework for validation.  There was also an organized way to begin completeness analysis.  Much easier to say “we’re getting this value” than to say “we’re doing these things – did we miss anything?”
• Slide 10.  I facilitated the folks in the room creating an Ishikawa from scratch.  We started with what we thought was the problem statement (provided by John Milburn from the back of the room) – “Traffic in Austin on Fridays is too bad.”  We ended with “John has work-life balance problems”, one of which comes from missing dinner with his wife, which can happen because of a combination of bad traffic and bad planning by John.  We also explored several solution-paths, including increasing the capacity of the roads and of the vehicles.  The ideas clicked for several people in the room.
• Slide 11.  Another real-world example, this one used in planning of a product roadmap for an 18-24 month view of the problems the team was signing up to solve.
• Slide 12.  Special thanks to the sponsors that made our inaugural ProductCampAustin a success!  My prediction for the next one (fall/winter 2008): 250 attendees.  So if you’re the sponsoring type, start planning on how you can help out.

Thanks again to everyone who attended, and special thanks to Tal Boyd of Seilevel, who video taped my whole presentation.  I just haven’t figured out how to split the 400+MB m4v file into something I can upload onto youtube.

We know the importance of identifying the use cases that enable our business goals. We also know the value of understanding the actors that will use our products. This article shows how to demonstrate a simple but powerful view that maps the use cases to the actors.

Why Map Use Cases To Actors?

Most use case templates and requirements documents include a place to list the actors for each use case. Very few encourage us to provide a big-picture view. Even users of requirements-management systems are left without an easy way to show this perspective. Can it really be valuable, if it is so often overlooked?

A critical element of defining and managing requirements is assuring completeness of your requirements. The first step to assuring completeness of your requirements is to acknowledge that the requirements represent a structure of decomposition of a problem.

Once you’ve identified the goals of the business (or the problems faced by customers within your market, when taking a multi-customer view), you need to recognize that those goals are achieved by enabling use cases. Each of those use cases is then enabled through the implementation of functional requirements.

Part of defining use cases is defining the actors (a.k.a. users) that perform those use cases. You can (and should) use an actor hierarchy to describe the users. If you fail to define the actors effectively, you risk creating the elastic user anti-pattern. This anti-pattern is what happens when you lose sight of the differences between different user groups. You run the risk of designing a solution that fails to meet the needs of any one group of users, by homogenizing them into a lowest common denominator user. Or worse, cutting user-experience corners, and designing “whatever is easiest” and justifying those decisions by rationalizing a schizophrenic actor who changes characteristics to suit your designs.

Most people defining requirements (product managers and business analysts) will do a good job of defining use cases, and identifying the actors that use them. And most tools and books provide good guidance on how to define an actor, or how to define the actors for a single use case. But so few can give you that big picture.

Requirements Iterative Development

If you have worked the entire lifecycle of a requirements process from problem to solution, you have experienced iterative requirements development. Most requirements processes work top-down (some prototype-driven processes are more “bottom up”). Define the goals. Then define the use cases needed to achieve those goals. Then define the functional requirements…

Hold on.

Don’t let that “agile requirements” vs “waterfall requirements” debate sneak in here. That’s a matter of formality and scale. What we’re talking about, specifically, is iterative development that happens as a result of insight, independent of (or in spite of) the process used. This applies to any process for defining requirements.

You define a set of goals. You may or may not validate that set of goals. You think you are done. You start defining the use cases and mapping them back to the goals. You discover two things. First, some goals are not mapped to any use cases, and second, some use cases are not mapped to any goals. You resolve this. You add and remove goals, and you add and remove use cases. The act of defining the use cases enlightens you about the goals they are intended to support. You are iterating on your goals. Unfortunately, a lot of project managers don’t understand this, and build a schedule around a milestone such as “business requirements approval”. Then when you apply your insights into a revision (iteration) of your goals, during the “use case development phase” the schedule is blown.

You do your change requests, reset expectations, and manage the political fallout of a schedule change. Then after “use case approval”, you move into requirements definition. As you document requirements, you uncover new use cases, or rewrite use cases, or otherwise benefit from the insights you have. And those changes to use cases propagate back up into changes in requirements. Now you’ve really messed up the schedule. The way some people fixate on schedules, you’d think they would rather stick their fingers in their ears and keep the schedule than benefit from improvements now, when they cost 100 times less to fix. Oops. Guess I went on a rant, there.

This is also commonly called “requirements churn” and can be tracked – either in a good way or a bad one. The bad way to track this creates an environment that discourages change (“you better keep the schedule!”). The good way to track this creates an environment of “get it (more) right the first time.”

One way to get it “more right” the first time with your goal definition is to look at the big picture with your use cases. One piece of that is mapping (or tracing) the use cases back to the goals. Another tool is to create a mapping between your use cases and your actors.

Use Case To Actor Mapping

Create a simple grid in a spreadsheet. Each row is a use case, and each column is an actor. In each cell, when the actor is the primary actor for a use case, add the letter “P”.

Primary Actor

The primary actor is the person who is the subject of the use case, performing the verb of the use case on the object. A use case may have multiple actors but has one most important person. The term actor represents the person who takes action – not someone playing a role. Other actors may be involved, either as participants, or as infrequent or secondary performers of the use case.
Some examples:

• Primary Actor: Pilot. Secondary Actors:Flight Crew, Sr. Maintenance Technician
• Primary Actor: Author.
• Primary Actor: Financial Accountant. Secondary Actor: Financial Accounting Manager

Foundation Series: How To Read A Formal Use Case

A simple grid with a handful of use cases and actors would look like the following:

The interesting analysis this allows you to do (and it is more powerful with a larger body of use cases and actors) is to review the big picture. You would ask yourself “who does each use case?” even without this tool. That’s just part of writing the use case. Now you can also ask “what use cases does each actor perform?” And you can easily see to ask questions like “If A03 does that, why can’t A02 do it?”

This big picture analysis, in my experience, will also accelerate the discovery of missing use cases. You should also capture when an actor is a secondary actor in the use case. You will then have a grid that looks like the following:

When asking the comparative questions about UC03, you uncovered another use case.

This tool accelerates those insights, allowing you to make changes “further upstream”, or if your glass is half-empty, correct fewer mistakes later.

Conclusion

Use the use case to actor map to provide a big picture view of how people will interact with your product. This view will improve your understanding of how people use the product, simplify the analysis, and encourage insights earlier in the requirements process.

The Cause and Effect diagram is also known as a fish bone diagram, because it resembles the skeleton of a fish. Using a cause and effect diagram can be the most effective way to define the problems that you intend to solve with your product. Get your stakeholders engaged in your program with this compelling visual!

Getting To The Root Of The Problem

In our recent article about writing good problem statements, we pointed out a common mistake people make with problem statements – they confuse the manifestation of a problem with a problem.

Problem manifestation [noun] – an example of a way in which a problem is exhibited, without appreciating the true nature of the problem. Ex: The problem manifestation is that the tires on my car are under-inflated. The problem is that my car is too expensive to maintain.

This distinction is relevant. The cost of operating the car is too high. That is the problem. It happens to be that one reason that the cost is too high is under-inflated tires. If you focus your energy on getting properly inflated tires, it will help (by improving fuel economy a little, and by reducing the frequency of tire replacement) with costs anecdotally. But you will not have solved the problem that costs are too high. Unless you get lucky. Costs can be high because the engine is inefficient or damaged, the aerodynamics of the car are bad, or any of a number of reasons. If you solve the problem by addressing a single manifestation of the problem, without understanding the whole problem, it is only because of luck.

Your Problem Statement is The Problem

In the comments on that article, The Demon points out that it is not always easy to identify the right level of abstraction for your problem. The cause and effect diagram makes it brilliantly simple not only to get to the root of the problem, but to communicate this cause-and-effect hierarchy of problem decomposition.

Cause And Effect Diagram Example

The cause and effect diagram is so visceral that the easiest way to communicate how it works is to show an example. Here’s what the cause and effect diagram would look like for the example problem above, where the cost of operating the car is too high.

[larger image]

The main problem is that the cost of operation is too high. This is the far-right, or fish-head part of the diagram (it is sometimes called a fish bone diagram).

The problem can be decomposed into three separate problems: spending too much on fuel, maintenance, and payments. Each of those problems can be further decomposed. Note that “under-inflated tires” appears twice – once as a cause of low miles per gallon (MPG) and once as an excess maintenance cost.

Alternately, you could recognize that spending too much on fuel could be due to lower fuel economy or excessively high prices. You could then choose to decompose the problem slightly differently:

[larger image]

Either approach results in crystal clarity that under-inflated tires is one root cause of low fuel economy, which is one cause of excessive spending on fuel, which is one cause of excessive operating costs. This visual approach helps significantly when trying to identify the right level of abstraction for expressing the problems in your problem statement.

Problem Abstraction Is A Side Benefit

The really cool part is that the help you get in finding the right level of abstraction for your problem is just icing on the cake. [Ed: No jokes about fish-bone cake. Ick!]

The real benefit comes in communicating and validating the problem decomposition with your stakeholders.

Someone questioned me once on the value of writing passionate requirements. Show one of these to your team, and you’ll get enthusiastic, passionate responses. You’ll get kudos from the business for demonstrating that you understand their needs. You’ll get praise from the implementation team for providing them with context.

Using Visio To Create A Cause And Effect Diagram

Creating a cause and effect diagram in Microsoft Visio is really easy, there’s a built in template, and it’s a good one. Create a new drawing and select the “Cause and Effect Diagram Shapes” template (under “Business Process”):

Visio will create a new drawing with a blank cause and effect diagram set up for you:

Fill in the boxes with the large problems. To get to the next level of detail (such as “Fuel Economy is Too low” in the last example), select the “Primary Cause” shape and drag it onto the diagram. Attach the arrowhead to one of the branches (the fish “ribs”) and start typing. For once, Visio’s default layout is where you want it.

To get a secondary cause shape (such as “Bad Aerodynamics” in the last example), select the “Secondary Cause” shape and drag it onto the diagram. Attach the arrowhead to the “primary cause” arrow you just created.

Conclusion

You already have a good justification for defining problems at the right level of abstraction. Now you know how to easily create a cause and effect diagram to find the right problem definition. As a bonus, communicating with stakeholders just got a lot easier – include this in your BRD.

In this article, we build on our ability to represent straight forward business relationships in UML class diagrams. These relationships describe how two objects are related to each other. Representing relationships in class diagrams helps us to better understand the domain and helps us to uncover hidden requirements. Occasionally, we have to deal with more complex relationships that involve more than two objects to properly describe. This does not happen as frequently, but when it does, our modeling efforts are more likely to uncover overlooked requirements. In this article we learn how to describe relationships that involve more than two objects.

Catching Up On UML Class Diagrams

If you navigated to this page first, it is the fifth in a series introducing UML Class Diagrams for requirements elicitation.

1. Uncovering Requirements With UML Class Diagrams Part 1: Discusses how to represent objects and entities from a business perspective.
2. Uncovering Requirements With UML Class Diagrams Part 2: Discusses simple relationships between objects or entities.
3. Uncovering Requirements With UML Class Diagrams Part 3: Discusses combining objects into collections and concepts.
4. Uncovering Requirements With UML Class Diagrams Part 4: Defines generalization (inheritance) and how to use it.
5. Uncovering Requirements With UML Class Diagrams Part 5: This article

Jump back to the other articles and get up to speed if you need. We’ll wait for you here. As a reminder, in this series, we’re specifically focusing on using UML class diagrams for uncovering requirements – as part of analysis, not design. We’re talking about what the business needs, not how the solution will work.

Understanding Details About The Relationship

One reason you may want to deal with more than two objects is obvious only after you change your way of thinking. So far, you’ve been thinking about objects (classes) and relationships (associations). Sometimes, when you need to understand the details of the relationship, you should think about the relationship as an object. It is both a relationship AND an object. And you draw this with an association class. We’ll walk through an example that illustrates the idea clearly, then we’ll look at the steps needed to create a relationship that is also an object.

Consider that you are gathering requirements to support software for tracking court cases – perhaps a mashup site that combines the latest public record lawsuits with entries from LinkedIn (my profile) and Crunchbase.

As part of your requirements gathering, you need to understand how these court cases work – so you start with a class diagram.

First – identify the main players in the lawsuits:

Both a plaintiff and a defendant are litigants, as they are involved in lawsuits.

That represents a simple relationship. A plaintiff sues one or more defendants. When you show this diagram to one of your stakeholders, she likes that you captured that one plaintiff can sue more than one defendants. She also likes that you can determine “who is the plaintiff suing” as well as “who is suing a given defendant.”

You point out one small problem – it is not clear if the plaintiff can only sue multiple defendants one-at-a-time, or if the plaintiff can sue multiple defendants in the same lawsuit. You get the answer (multiple defendants can be sued at the same time), and as you start to scratch your head about how to represent it, your stakeholder interrupts (they do that):

“We need to be able to show lawsuits with a “most recent” view, and a “largest” (in dollar amount) view on the main page of the site!” You realize that your diagram doesn’t work, and you make a note to yourself about the multiple-defendants issue.
You need a way to capture information about the suit. Suddenly, instead of a verb (sues), you need a noun (suit). You need to reason about the relationship. So you update your class diagram.

Your updated diagram now shows that a single plaintiff, in the context of a single suit, can sue multiple defendants. You also capture that you need to know the trial date and the dollar amount of the suit. You erase that note to yourself, because your diagram now clearly indicates that one lawsuit involves multiple defendants. You make another note to yourself that it is not clear if a plaintiff can be involved in more than one suit with the same defendants (he can). You’ll deal with that later.

What you’ve drawn is something (the suit) that is both a relationship and an object. In UML class diagrams, this is called an association class.

Creating An Association Class in a Visio UML Class Diagram

To create an association class, you use the Association Class shape in the Visio UML Static Structure stencil.

Drag the association class onto the page.

By now, you realize that you need to suppress the end names in the display. Right click on the shape and select “Shape Display Options…”:

And disable the display of the end names:

Now your shape will look like this:

You can manipulate the shape and its placement in two different ways. You can select and drag either line end (to connect to another shape in the diagram)

Or you can drag the “class” portion (the box) of the shape to wherever you want to place it. [Note: When you drag the class, it looks like you are disconnecting the line from the shapes and messing everything up. It is not happening. When you release the mouse button, the class will be where you put it, and the line will still be where it was before.] There is a dashed-line that connects the class (the box) to the association (the line). Visio automatically updates that for you – you never have to worry about it. In fact, if you don’t like it where it is, you can’t do anything about it either.

You could use the rotate-handle (the green circle on top) to rotate the box, but please don’t. Class diagrams, by convention, are drawn with everything aligned with the page. To get the line on top, just drag the line ends above the shape (or drag the shape below the line ends).

You use the same rules for showing directions with an association class that you do with a regular association. If the business needs to think in one direction – “Who has the plaintiff sued?” then show that arrow. If the business wants to think in the other direction – “Who has sued a particular defendant?” then show the opposite arrow too.

Even More Complex Relationships

The cool shape above lets you draw a three-way relationship. It is most handy when you need to understand something about the relationship itself – treating the relationship as a noun instead of a verb. You can create relationships in UML class diagrams that involve more than three objects. These are called N-Ary Associations. The “N-Ary” part is geek-speak for “binary, trinary, quaternary, etc” – any number is valid.

Earlier, we glossed over one question – “Can a single plaintiff, related to multiple defendants in the context of a single suit, also be related to those defendants by another suit?” You can use an n-ary association to depict this.

In the Visio UML Static Structure stencil, select the N-Ary Link shape.

Drag it onto the page

It looks a bit like a decision diamond from a flow chart, but with handles. Drag it to where you want it to be in your diagram and then start connecting the line ends to the related classes.

After you’ve connected the ends (or before, but after is easier), double click on the shape to bring up the properties dialog.

You’ll see three “Link Ends” – just rename them to show the multiplicity of the connections. You will end up with a final diagram that shows:

One plaintiff can sue one or more defendants in one or more suits. You could (and I will) argue that this is even more ambiguous than the previous diagram.

• Who does the suing? Is it the plaintiff, the defendant, or the suit itself?
• Are they even suing? Perhaps the relationship is just “they are all in the same room at the same time.”
• When a plaintiff sues multiple defendants, is it one defendant per suit, with multiple suits? Can it be? Must it be?

Personally, I never use an n-ary association when modeling complex relationships. I much prefer the association class.

A Simpler But Busier Alternative UML Class Diagram

You never have to use an association class. You can always represent the situation with three classes and two associations as the following diagram shows:

Instead of an association class, you create a single class (suit) that represents the noun, and you break up the single association (suing) into two association (attacks with, defends against). In some ways, this is more precise than using an association class. You can tell from the diagram above that

• A single plaintiff attacks with one or more lawsuits.
• One or more defendants defend against a single lawsuit. Therefore, there could be two suits between the same plaintiff and the same defendants at the same time.

What you lose is a notion that the suit establishes the context of the relationship between the plaintiff and the defendant(s). Ultimately it is a judgment call about which form to use (the association class or the normal class with two associations). If understanding the specific multiplicity data is important, you should use the two-association diagram. If it is not, I personally feel that the association class provides clarifying context.

Next Up

In the first five parts of this series we’ve covered

• Using classes to represent business objects and entities.
• Using simple associations (relationships) to demonstrate how objects are dependent or how they relate to one another.
• Using composition and aggregation to show how objects are treated when grouped together.
• Using generalization and inheritance hierarchies to show how similar, related objects can behave differently.
• Using association classes and n-ary associations to express more complex relationships.

If you understand all of these concepts, you are ready to create UML class diagrams of the business domain and concepts. You are ready to use these tools to uncover otherwise hidden requirements. If you want to study some of the more arcane details around UML class diagrams, you should be ready to read Scott Ambler’s articles.

• UML 2 Class Diagrams – an explanation, in detail, of how and what and why to draw things a particular way
• UML 2 Class Diagram Guidelines – advice on how to make your diagrams consumable and appealing

Just keep in mind that Scott jumps right into complex topics (which you are now ready for), and also includes tips and advice that are only relevant when creating class diagrams of implementation designs. Just filter that stuff out. Or come up with a way to leverage those details to the modeling of business ideas, and share them here.

Thanks for following along this far, and if you have any questions or would like to see us cover anything else about using UML class diagrams for uncovering requirements, add a comment below.

The hardest part of gathering requirements effectively is uncovering the requirements that people don’t immediately tell you. You have to ask the right questions. And one of the best ways to find the right questions to build a class diagram of the business domain. This article continues our introduction to class diagrams.

Catching Up on UML Class Diagrams

If you’ve found this article first, there are three that came before it.

1. Uncovering Requirements With UML Class Diagrams Part 1: Discusses how to represent objects and entities from a business perspective.
2. Uncovering Requirements With UML Class Diagrams Part 2: Discusses simple relationships between objects or entities.
3. Uncovering Requirements With UML Class Diagrams Part 3: Discusses combining objects into collections and concepts.
4. Uncovering Requirements With UML Class Diagrams Part 4: This article.

So jump back to the other articles and get up to speed. We’ll wait for you here. As a reminder, in this series, we’re specifically focusing on using UML class diagrams for uncovering requirements – as part of analysis, not design. We’re talking about what the business needs, not how the solution will work.

Generalization: A Dog Is A Mammal

We’ve looked at objects and relationships between them. We’ve looked at the special association relationships that give us aggregation and composition. Generalization is another form of relationship, but not one that tells us how different objects interact – one that helps us better describe objects. We could talk about a dog, and create an object that represents a dog. But what if we also wanted to talk about a horse? They have some things in common, because they are both mammals. Generalization allows us to talk about mammals too. That’s fine, but let’s use a business example instead of a classroom example.

The key to this generalization relationship is to think about the phrase “is a.” A dog is a mammal. Don’t confuse this with combining objects into an aggregation. A pack has a bunch of dogs in it. A zoo has a bunch of mammals (and other animals) in it. But a dog is not a specialized pack. It is a specialized mammal.

Remember “…is a…”

This relationship carries special meaning – all things (characteristics, behaviors, etc) that are true about the general object are true about the specialized object. But all things about the specialized object are not necessarily true about the general object.

• All mammals have hair, therefore all dogs have hair.
• All mammals have live babies (they do not eggs), therefore all dogs have live babies (puppies).
• All dogs are pack animals, but all mammals are not (elephants are, but shrews are not).

Technical folks usually call this inheritance – the specialized object inherits all of the properties and behavior of the generalized object. Inherit is almost as good of a word to use as generalizes. Where inheritance really helps as a term is it allows us to think in terms of parents and children objects. The mammal is a parent and the dog is a child of mammal. The terms parent and child make it much less cumbersome to talk about generalization relationships.

Understanding Insurance Policies With Generalization

Consider that you’re working on a project for a life insurance company. In your first conversation with a subject matter expert, you hear five different terms for describing insurance policies. At a convenient pause, you stop the interview, walk over to a white board, and draw class diagram objects for each of the five items.

You ask your expert how all these objects are related to each other. She explains that all life insurance policies are either term policies (they last for a fixed term of time) or permanent policies (they last for as long as the premiums are paid).

You recognize this as a generalization relationship.

• Every Term Policy is a Life Insurance Policy
• Every Permanent Policy is a Life Insurance Policy

Your SME also informs you that permanent policies, as a form of investment, are always one of two special types – whole life policies and variable insurance policies. Whole life policies have a fixed return for a fixed premium. Variable policies invest your premium in market securities, and the amount of money available at the time of payment depends upon the performance of the policy. More generalization relationships.

• Every Whole Life Policy is a Permanent Policy
• Every Variable Insurance Policy is a Permanent Policy*

[*As far as I know. If there is such a thing as a variable term life insurance policy, my apologies - just assume that your company does not sell one.]

You draw the generalization relationships on the white board, and you move forward in eliciting requirements. This drawing is known as a hierarchy.

Drawing Generalization Relationships in Visio

You use the generalization shape in visio to create generalization (inheritance) relationships between classes in your class diagram.

As you drag it onto the page, it looks like the following:

The shape is an arrow with a closed (but not filled) arrowhead on one end. You connect that arrowhead to the parent class – the more-general of the two. The tail is connected to the child class – the more-specific of the two.

Once you draw all the relationships, your Visio class diagram will look like the following:

Now you’re prepared to understand the other information your subject matter experts are sharing, in the context by which the business is describing their requirements.

This hierarchy makes sense, but it seems to be completely different from all the other class diagram stuff we’ve done. How can you combine these different views? It is the combination of them that really brings out the value.

Relationships, Classes, and Inheritance

The first thing to realize is that association relationships, composition relationships, and inheritance relationships can all happily co-exist within the same UML class diagram. In fact, much of the insight you gain into uncovering requirements only comes when you combine these different analyses within a diagram.

The structure we looked at above provides a good description of how a company manages the policies that they write. What you are likely to want to document are requirements around selling those policies. Each time a policy is sold, an agreement is created. That agreement is a copy of the policy sold (at the time of selling it), with the insured person’s name filled in. You can imagine the policy to be a form with blanks that need to be filled in. Each time a policy is sold, someone makes a copy of the “official” policy, fills in the blanks – name of insured, policy dates, etc – and then it becomes an agreement.

Introducing the term agreement allows the business to treat the two ideas separately. A policy defines the agreements that can be sold at any given time. An agreement is one policy, as sold to an insured person (customer).

[click for larger diagram

As you can see from the diagram, we have the same hierarchy for describing insurance policies. We've added some other objects and relationships.

Objects

• Agreement. A policy written by an agent for an insured person. The agreement is written in a specific state.
• Agent. An agent is someone who sells insurance policies (agreements). The agent lives in a specific state.
• Insured Person. Someone who purchases an insurance policy (agreement). The person lives in a specific state.
• Insurance License. An official document that allows someone to sell policies in a specific state for a period of time.
• NASD License. A special license from the National Association of Securities Dealers that allows someone to sell variable insurance policies.

Relationships

• A life insurance policy is used as a template for an agreement.
• An agreement is written by an agent.
• An agreement is held by an insured person
• An agent holds one or more insurance licenses.

From the diagram, we can understand that an agent sells an agreement to an insured person. That agreement is based on a life insurance policy. The agent holds at least one license to sell insurance.

Notice the relationship between the agreement class and the life insurance policy class. The life insurance policy is at the top of an inheritance hierarchy. Each other type of insurance policy (term, whole life, etc) is just a specialization of life insurance policy. The diagram depicts that the agreement can be one of any of the different types of insurance policy. And therefore, an agent can sell any of the types, and an insured person can hold an agreement of any of the types of insurance policy.

When reviewing these relationships, you discover that this is an overly simplified representation. You capture the additional information and update your diagram.

More Complex Class Diagram

As part of reviewing the diagram, you discover that variable insurance policies are treated very differently than other insurance policies.

• An agent must have a different type of license (an NASD) license to sell variable insurance. Because of this, the business treats these agents as being special - they are called "Broker / Agents" and are subject to many different internal policies and procedures. Some of those policies represent enforcement of legal regulations, and others are internal policies.
• A broker / agent can sell both variable and fixed (non-variable) insurance policies.
• A variable policy is a combination of a fixed policy and an investment. As such, the business thinks about those customers as investors, and not just insured people. This distinction is really only relevant to sales people and marketing - who will use different approaches to sell to people who want investments.

You update your class diagram to look like the following:

[click for larger diagram]

This diagram is much more complicated.

• We enhanced the hierarchy for insurance licenses to reflect that broker/agents need a different type of license (NASD license) to sell insurance.
• An insured person holds a fixed agreement, where an investor holds a variable agreement.
• An agent can only write a fixed agreement, where a broker/agent can write any type of agreement (fixed or variable).

The diagram is almost too complex to absorb within a UML tutorial. If you were writing these requirements, and did not create a similar diagram, you would be in trouble. In the best case, you would end up with an implementation that met all the requirements, but did not use a good implementation design (due to lack of context). It is more likely that either you would miss some requirements, or your implementation or test team would miss some.

The diagrams that have had the most impact, in our experience, are diagrams that have a similar level of complexity.

Next Up

In the first four parts of this series we’ve covered

• Using classes to represent business objects and entities.
• Using simple associations (relationships) to demonstrate how objects are dependent or how they relate to one another.
• Using composition and aggregation to show how objects are treated when grouped together.
• Using generalization and inheritance hierarchies to show how similar, related objects can behave differently.

All of the tools you’ve learned so far deal with binary associations – an agent sells a policy, a book club reviews books. In the next article, we will look at relationships that involve more than two classes.

Uncovering Requirements With UML Class Diagrams Part 5: Complex Relationships

UML Class Diagrams are very effective at uncovering requirements. They give us insight into how the business thinks about objects and their relationships. And from that understanding, we think to ask questions we might otherwise overlook. In this part of our series, we look at how to represent when one object is made up of other objects. The two types of relationships we explore are composition and aggregation.

Catching Up on UML Class Diagrams

If you’ve found this article first, there are two that came before it.

1. Uncovering Requirements With UML Class Diagrams Part 1: Discusses how to represent objects and entities from a business perspective.
2. Uncovering Requirements With UML Class Diagrams Part 2: Discusses simple relationships between objects or entities.
3. Uncovering Requirements With UML Class Diagrams Part 3: This article.

So jump back to the other articles and get up to speed. We’ll wait for you here. As a reminder, in this series, we’re specifically focusing on using UML class diagrams for uncovering requirements – as part of analysis, not design. We’re talking about what the business needs, not how the solution will work. UML class diagrams can be used for both, and most tutorials are written for programmers doing design work. This one is written for people who work with requirements.

Relationships of Combination

When a collection of bananas are combined, we call them a bunch. Crows exist in a murder, and lions in a pride. Teams are made up of players. It is a deck of cards. An order is a collection of line items. We have always had the notions of both individual items (or people) and combinations existing as an interesting entity. Sometimes we treat them the same – you can eat a banana or a bunch. You can feed a lion or a pride. Sometimes, we deal with the combined entity. You shuffle a deck, you fulfill an order.

Understanding this type of relationship can be very important to understanding what your customer (aka “the business”) needs. You are describing the mental model of the business. Business people think about fulfilling an order, not “fulfilling all of the items on the order.” A user may want to archive the history (all the previous versions) of a file, or she may just want to keep the most recent version. Thinking about these concepts helps you uncover the requirements.

There are two jargon terms – aggregation and composition – that apply when we talk about multiple things as one combined thing. They have precise meanings.

• Composition – when one item is part of another item, the relationship is composition.
• Aggregation – when one item can be included in another item, the relationship is aggregation.

If that doesn’t make sense, this “formal” distinction will really mess you up:

Composition is a stronger form of aggregation where the whole and parts have coincident lifetimes, and it is very common for the whole to manage the lifecycle of its parts.

Scott Ambler

Here are some examples that may simplify things:

Composition

• A building is composed of one or more rooms (a room is part of a building)
• A plane is composed of a fuselage, one or more engines, and one or more wings (a wing is part of a plane)
• An order is composed of one or more line items (a line item is part of an order)

Aggregation

• A team includes more than one players
• A library includes more than one books
• A market includes one or more customers

Ambler’s definition makes sense, when you think about these examples. You could shut down a library without destroying the books – likewise, you could kick one of the players off a team and the team would still exist. That’s what he means by coincident lifetimes.

Drawing a Composition Relationship With Visio

To draw a composition relationship in Visio, you use the composition shape from the UML Static Structure stencil.

When you first drop this shape on the page to connect two classes, it looks like the following:

There is a solid black diamond on one end (the first end) and nothing on the other end. In UML, this is stating that an order is composed of line items. By default, Visio shows the “end names” as it did with the association shape. You can fix it the same way we did before. Right click on the line and select shape display options.

Then make the same modification we did before, to show the shape name and suppress the display of the “end names.”

Now you have the kind of display you want. Note the check marks at the bottom of the dialog – you only have to make this change once per class diagram. Unfortunately, Visio does not remember this change, so you have to do it once for every diagram (every new file, and every new tab within the same file). Annoying.

Double click on the line to update the information about this composition relationship.

You will end up with the following (we re-arranged it to make it easier to read):

Drawing an Aggregation Relationship With Visio

Drawing an aggregation relationship is almost the same as a composition relationship with Visio – it just requires an additional step.

In this example, a book club reviews books. You want to show that the book club includes members. Note – members can come and go without causing the book club to be disbanded. You can think of aggregation as membership in a combined entity.

First, use the composition shape again (the same as above), and update the properties as we just did. You will see

The Visio stencil does not include a special aggregation shape, so we will cheat by changing the formatting of the composition shape. Select (in the menu at the top of the window) format > line…

And in the dialog, you will change the display of the “Begin” end-point.

Aggregation is represented in UML Class Diagrams with the same diamond-shape as composition. The difference is that the shape is “empty” instead of being a solid black diamond. Click “Apply” and “OK” and you end up with what you want:

Note: If you change the format of the composition line first, and then change the properties (“Joins” etc), Visio will reset the line end to be a solid diamond again. It resets. Annoying. If you copy an aggregation line, the copy reverts to the solid diamond again too. Very annoying.

Next Up

Up to this point, you’ve learned how to define classes (and attributes), simple relationships (A book club reviews books, and a member reads books), and combinations of items as compositions and aggregations (an order is composed of line items, and a book club aggregates members).

Next, we will cover hierarchies, usually thought of as “Is a” relationships. A Sales Rep is an employee, and an employee is a person.

Uncovering Requirements With UML Class Diagrams Part 4: Generalization (inheritance) and how to use it.

We continue our exploration of UML Class Diagrams with this article that explores how to represent basic business relationships in a class diagram. Drawing these relationships can dramatically clarify requirements documents. Using a class diagram to supplement other requirements documents provides for a centralized reference that enables a shared understanding of the problem domain. That understanding prevents mistakes in interpreting requirements.

Getting Up To Speed

We started this discussion of class diagrams last week. In it, we presented the notion of a class. When a stakeholder cares about a concept, idea, or thing, we represent it as a class.

The business cares about customers. And customers have addresses and credit ratings.

Classes and Attributes

How do you know when something should be an attribute, and not another class? In our example above, think about Customer and Address and Credit Rating. One way to make a distinction is to say that if an attribute has other attributes, it should be a class. A credit rating is just a number. But an address is a compound object made up of multiple attributes.

An address can have multiple lines of street address information, as well as city, state, zip code and country information. That is a good indicator that it is likely to be a class of its own. If we were to represent an address as attributes of a customer, we would have to include each of the “sub attributes” as a separate attribute of customer. That feels bad, from a design standpoint.

The distinction is one of design, but generally speaking, if the concept stands on its own, it should be its own class. An address is related to the customer. A credit rating is a property of a customer.

Simple Relationships

How do we show a relationship between a customer and an address?

The customer receives bills at an address. That is the relationship between the customer and the address. The business wants to know where to send bills for the customer. We’ll talk more about relationships in a bit. First, we’ll cover the steps in visio for creating the relationship shown above.

Showing Relationships With Visio’s UML Stencil

The relationship shown above is called a binary association, because it shows the association between two classes. There is an object (Visio calls it a “master shape”) in the Static Structure template for creating these, aptly named binary association.

Drag that onto the page, and connect the two classes for which you wish to show a relationship.

The default display properties for the binary association shape cause the shape to display some weird information – called the “end names” of the relationship. The shape also does not give us the arrowhead, or the name of the relationship, Receives Bills At. Right click on the line and select “Shape Display Options…”

Remember this, you will use the dialog that pops up a lot.

We want to do three things for now:

1. Check “Name” so that the name of the relationship (Receives Bills At) will show up.
2. Un-check “First end name” so that it is hidden.
3. Un-check “Second end name” so that it is hidden too.

Click OK, and the shape will have updated to look like the following:

The name is defaulted (to “Association1″), and no arrowheads are showing up. We also have two asterisks, an no “1.” We need to update the shape’s properties (not display properties) to include that information. Double click on the line and you will see the following dialog (Fill it out to match):

[click for full size view]

• Name: Enter “Receives Bills At.” for the name. Note – some people prefer mixed case or lower-case. Any approach is fine, just be consistent. The name is the name of the relationship and it indicates the meaning of the relationship.
• Name Reading Direction: forward and backward will confuse you. It confused me for years. This is what determines where the small solid triangle shows up to indicate the direction of reading. Customer Receives Bills At Address, instead of Address Receives Bills At Customer. One day, I realized that this field only controls if the triangle shows up before or after the text. With up-down relationships, I still get confused. Use the standard of top-to-down is the same as left-to-right, and you’ll eventually get used to it.
• Association Ends: This section shows the two ends as rows in a table – with five columns describing each end. For now, we will only focus on the last two columns. This is another area for confusion – the first row represents the top-left end of the line (when you drag it onto the page) and the second row represents the bottom-right end of the line. You can move the ends of the line around after you place it on the page, and the rows in this table will maintain their original associations. Try not to get frustrated when you get these backwards. I still make that mistake all the time, after creating a few hundred diagrams over the course of a decade. Think of the top-left end of the line as the “first” end, and the bottom-right as the “second.” Then when you move it around, you might remember which is which. If you get in the habit of attaching the line first to the “from” class, and then to the “to” class, you will start to get the hang of it.
• Multiplicity: Multiplicity allows you to specify how many objects can be on either end of the relationship. In our example, a customer can receive bills at only one address, but multiple customers could share the same address. My stepdaughter and I each have iTunes accounts. We are two separate customers, but we have the same address. Since I attached the “first” end to the Customer class, there is an asterisk in the first row, and a “1″ in the second row. [*See below for explanations]
• IsNavigable: Either the UI designers for Visio expected all of their users to be Java programmers, or they ran out of space. “IsNavigable” can be translated into “Should the arrow be shown on this end of the line?” Since, as a business, we care about the address at which a customer receives bills, we show the arrow for the “second” end. But we don’t anticipate (commonly) needing to determine all of the customers that receive bills at a particular address – so we don’t show the arrow in the opposite direction.

Types of Multiplicity

There are a few different concepts that can be displayed for multiplicity. Your developer co-workers and math geeks will call this cardinality. That’s probably even the better term to use. But since Visio chose multiplicity, so will we, at least for this article.

• 1: Exactly one object of this type is involved in the relationship. A customer has one billing address.
• *: Any number of objects (or none at all) are involved in the relationship. Any number of customers can receive bills at a given address.
• 0..1: Zero or one objects are involved in the relationship. A driver may or may not have a drivers license.
• 0..*: Same as “*”
• 1..1: Same as “1″
• 1..*: Any number of objects (as long as there is at least one) may be involved in the relationship. A shipment can include any number of items, and it must include at least one item.

This brings us back to our original relationship example.

The small class diagram above represents the following:

• A customer has a credit rating.
• An address includes three fields for “street information”, city, state/province/county, zip or postal code, and country fields.
• A customer receives bills at exactly one address.
• Any number of customers (or none at all) can receive bills at any one address.

Simple Relationships Revisited

With the mechanics of using Visio out of the way, we can show some examples of some other simple relationships.

• A sales rep sells products to any number of customers.
• Any number of customers purchase products from a sales rep.

Both examples above depict the same relationship, and either is acceptable. What would be bad would be to use the passive voice and say “any number of customers are sold products by a sales rep.” This is the same advice that applies when writing use case names – don’t use passive voice.

There are opportunities to misread requirements when relying solely on UML. Imagine we had a requirement that any customer always make purchases from a single sales rep. The goal is to provide a sense of relationship for that customer. Both of the diagrams above technically express that requirement. If a customer could have more than one sales rep, we would show “1..*” instead of “1″ for the multiplicity on the sales rep side of the relationship.

Someone reading the examples above could reasonably be unsure about the intended requirement. Is there a single sales rep for a given transaction? Is there a single sales rep for a given customer, regardless of the number of transactions? Only the latter interpretation is technically accurate – but either is a reasonable interpretation. Professor Daniel Berry, author of The Ambiguity Handbook [The actual title is From Contract Drafting to Software Specification: Linguistic Sources of Ambiguity, A Handbook], explained in a lecture last year at the 2007 IBRF that UML stands for Undefined Modeling Language. This is a good example of that.

By including the diagram within, or as a reference from, a requirements document, you provide both the context and the graphical clarity needed to understand the intent. Don’t rely solely on the diagram!

A product has a price. One product has one price. This relationship is almost too simple, making it difficult to come up with a good name for the relationship. “A product has a price of price” is awkward.

“A product will be sold for a price” is better. If we were limited to “has a”, we could make an argument that the price should be an attribute. But the price may have properties (like currency used), or may be calculated dynamically based on coupons or contracts.

Using action verbs will help with both understanding and elicitation. If you are reviewing the diagram above with a stakeholder, you are not likely to get any discussion from “product has a price” – of course it does. But if you show “product will be sold for a price” you will immediately trigger responses. Especially if you ask “how do you know what price to sell the product for?” Use active verbs with explicit meanings instead of “weasel words” like “has a.”

This is a very clear way to indicate that from a business perspective, the customer has a billing address and a shipping address, and no reason to expect them to be the same. If you have to worry about export compliance, you may add an “end use” address – the location where the product will ultimately be used. Imagine how messy that would be if we had used attributes instead of classes!

As messy as that would be, this highlights why we use classes. Think about some other business relationships we have not drawn. Credit card authorization uses the billing address. Taxes may be* calculated based upon the billing address or the shipping address. Shipping charges would be based upon the shipping address. [*I believe that for physical goods, the shipping address is used, and for electronic downloads, the billing address is used.]
There is no limit to the number of entities and relationships that can be represented in a class diagram. As a guideline, think about usability. Are you producing class diagrams as part of exploring specific areas of the business? Are you making sure that a complex set of relationships do not get oversimplified? Are you “boiling the ocean” with a giant encyclopedia of the business domain? If you are – why?

Summary So Far

So far, we have discussed classes as a means to represent entities from a business perspective. We’ve also introduced some simple relationships. Those relationships show how pairs of entities interact or inter-relate. We’ve shown how to make the relationships directional and bidirectional – depending on which way(s) the business needs to look at things. And we’ve covered multiplicity – how many of each type of object are involved in the relationship.

There is still a fair amount of ground to cover between here and Scott Ambler’s comprehensive reference. If any of the concepts so far are unclear, or if there’s something you want to make sure we cover – add a comment!

Next Up

In our next article on using UML Class Diagrams for unearthing requirements, we will look at more complex relationships.

Uncovering Requirements With UML Class Diagrams Part 3: Combining objects into collections and concepts.