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.

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.

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.

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.

We’ve been promoting use cases as the right way to approach agile requirements, and in a recent article, Alistair Cockburn stresses the importance of use cases. Over the last three years, he has found that teams that avoid use cases consistently run into the same three problems. We defer, of course, to Alistair as the expert. But we’ve been independently promoting this practice too. So today, we get a cookie!

Alistair Promotes Use Cases for Agile Development

First, a hat tip to Rajeev Singh for pointing us to Alistair’s defense of use cases in agile projects. In discussing his findings from the last three years of talking to agile project teams, Alistair writes:

I keep running across organizations suffering from three particular, real, painful, and expensive problems.

[...]

In particular, use cases fix those three problems.

I’ve been testing this out for the last 3 years – I walk in and ask, “On your agile project(s), do you by any chance suffer from any of these three things?” … and then list the three … Much stronger than even I expect, there hasn’t been a single organization I asked these of that hasn’t said, “Oh, Yes, and How!”

Why I still use use cases, Alistair Cockburn

Alistair finds these problems both when teams replace use cases with user stories (or use scenarios) and when they eliminate either approach and move to a feature-driven product backlog.*[See "Scrum" Section at the end of the article.]

Paraphrasing the three problems (“Without use cases, …”):

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.

How do use cases address these problems?

1. Gaining Context With Use Cases

Even in agile projects, use cases are an enabling mechanism for companies to achieve goals. An approach that uses structured requirements provides that context.

Each use case exists in the context of the goal. A couple years ago we wrote about the reasons for writing use cases. Those goals could easily be addressed with use scenarios and user stories. The problems that Alistair articulates arise from choosing something other than use cases to meet those goals.

2. Getting An Early Indication of Scope

Politically, the largest problems in getting an agile project launched in a waterfall organization comes from mis-set expectations. Setting expectations and thereby securing both funding and support for a project can be more important than execution.

If you don’t have the support of a sponsor, your project will fail. If you have sponsorship and funding, your product could still fail. Both are necessary, neither is sufficient.

To set expectations, you have to identify the scope of your project immediately. Here’s an example of the scope definition for our nexus project from last year. Setting scope is as much about managing stakeholders and prioritizing stakeholder objectives as it is about controlling delivery time frames and schedules. [Tangent Warning: even if it means delivering incomplete requirements.]

The key is to get a breadth-first overview of the scope, and then a deep understanding as you iterate.

3. Avoid Scope Creep With the Rigor of Use Cases

As Alistair points out, this is hard to differentiate from “managing scope.” The distinction is that the scope-definition issue is one of discovering functionality broadly, where this scope creep issue is one of understanding complexity sufficiently.

The right approach to defining use cases for agile development starts with a definition of scope. Once you’ve defined the scope, you define the use case names, then progressively prioritize and define the use cases in more detail, in priority order, as you incorporate them into your time-boxed project schedule. You also refactor your use cases, consolidating and defining subordinate use cases where appropriate, and defining extension use cases as needed.

Scrum

Scrum, as an organizational approach to agile does not preclude the use of use cases. Scrum projects commonly choose to use a feature-driven backlog. We actually really like scrum as a mechanism for managing delivery. But we feel that it works most effectively when time boxing each iteration specifically in terms of use cases. When using use cases as the quanta of your iteration backlog, you get all the benefits defined above, plus the benefits of Scrum as a delivery vehicle.

Conclusion

Use Cases Rule! ["If it's our blog, then it's our pizza." - Mr. Hand from Fast Times at Ridgemont High]

Learning how to write use cases can be tough, but it is simple compared to the balancing act of determining which use cases to write and how to manage the expectations of all the stakeholders that are involved. It can be a difficult balancing act to prioritize use cases to assure that you meet the goals of the business while satisfying the needs of the users.

Goal Driven Use Cases

In the world of structured requirements, we apply an approach of top-down decomposition to determine what we need to build.

In an article stressing the importance of non-functional requirements, we summarized the relationships from the above diagram as follows:

• Goals are achieved by enabling use cases.
• Goals drive non-functional requirements.
• Use cases are enabled by implementing functional requirements.
• Use cases influence non-functional requirements.
• Non-Functional Requirements define the characteristics of functional requirements.
• Functional requirements drive design decisions
• Design choices are restricted by constraints
• Design choices guide implementation
• Implementation is product

Non-Functional Requirements Equal Rights Amendment

The key element, with respect to this article, is that goals are achieved by enabling use cases. In other words, without the use cases that people* perform, the goals of the business can not be achieved.

[*Sometimes the use case is performed by a system - not all actors are people]

Principal Stakeholders Own Business Goals

We learned a lot from Outside-In Software Development, by Carl Kessler and John Sweitzer. One of the important things we learned is how to understand the goals of principal stakeholders. Principal stakeholders are the “owners” of the ROI that we are attempting to achieve with our product or solution. The business has the goals, but the business is an abstract entity. If the goal of the business is to increase sales by 10%, we can’t call up the business and ask “did we meet your goal?” We have to call up the vice president of sales. The business is organized so that there are people who are responsible for the initiatives and goals of the business – they are responsible for growth, profitability, costs, strategy. The insight we got from Kessler and Sweitzer is an appreciation that this ownership lies with one or more individuals.

When a goal has an owner, we can validate that we have met the goal. We can validate that we have satisfied the owner of the goal. You can’t do that validation with an abstract entity, a “business”, but you can with a person. Certainly, we can do the math ourselves, but if we want someone to pay the bills – and more importantly – invite us back to do more projects, we have to satisfy an individual. And that individual is our principal stakeholder.

Principals Own Use Cases

Our principal stakeholder owns the business goal – and therefore owns the use cases that enable that goal to be achieved. Our stakeholder will validate the completeness of our use cases by answering the question, “If we enable all of these use cases, will we completely meet your goal?”

End Users Own Use Cases

User-centered design is also one of our core principles, and an acknowledged best-practice. For many companies, it is more than mandatory – it is a way of life. The entire software development process is sometimes built around a focus on the end users. This approach puts the user in the center.

You can identify end user goals with the following approach:

1. Identify the actors that interact with the software.
2. Identify the personas that represent those actors – thus avoiding the elastic user syndrome.
3. Develop an understanding of the personal goals of the personas – and by extension, the actors through ethnographic research.

Stakeholder Goals: Principal vs. End User

This creates what appears to be a conflict – do principals own the use cases, or do end users own the use cases?

Mixing Interaction Design With Structured Requirements

One approach to resolving this conflict is to eliminate it by mixing interaction design with structured requirements. In this approach, the interaction design component applies end user ownership as an input to the design, but not the content of the use cases, as the following diagram shows:

In the diagram above, the changes (relative to the Wiegers process) are marked in blue.

The interaction design process starts with two parallel activities. On the left is the identification of corporate goals, which is analogous to the creation of an MRD. An MRD can be a reasonable mechanism for documenting the corporate goals. It provides more detail than “Increase profits” with statements like “Increase profits with improved pricing.” On the right side is the creation of personas to represent the most important users.

Interaction Design and Structured Requirements

This approach side-steps the issue by relegating the end users to “design input” and not allowing them to contribute to prioritization and management. For many applications, this is a great way to approach things. Specifically, it works very well when the user’s goals are tightly coupled or highly aligned with the principal stakeholder’s goals.

When Goals Conflict

User goals are not always aligned with stakeholder goals. In our earlier article on identifying these conflicts, we proposed a simple grid view for identifying these conflicts.

In that article, we looked at situations where the goals of the actor were primarily aligned with those of the principal stakeholder, and therefore the business. We discussed using the grid to inspire solutions that removed the conflicts. Two birds with one stone would be the easiest way to summarize.

What about when goals are implicitly in conflict – or even diametrically opposed? We’ve worked on systems where that is exactly the case. Consider a two-tier sales model, and products / websites designed for the people in the second tier.

Two-Tier Sales Models

Here are some common business models where the users have goals that are directly in opposition to the goals of the principal stakeholders.

• Automotive Manufacturer and Dealer. A website, designed by a car manufacturer, to allow dealers to improve their ability to sell cars. The automotive manufacturer makes money by selling cars to the end customer, and the dealer makes money by causing the sale to happen. The manufacturer is compensated by profits on the sale, whereas the dealer is compensated simply by making the sale. In other words, the dealer is motivated to lower the price because a sale at any price generates the same profit for the dealer. The manufacturer is motivated to raise the price because fewer sales at a higher margin generate the same profit, but higher ROA (return on assets) than more sales at a lower margin. This is an implicit conflict.
• Book Publisher and Book Retailer. A book publisher sets a price for sale to the retailer, and a suggested (list) price to the end customer. The retailer will typically pay a negotiated discount, in the form of a percentage off list, for the book. Any books not sold by the retailer are returned to the publisher or (usually) destroyed. The retailer does not have to pay for books that are not sold. The retailer has limited shelf-space, and makes money based upon a combination of the size of the discount and the number of books that are sold, regardless of publisher. The retailer is therefore incented to increase the discount, and thus increase profits for a particular title – and the publisher is incented to reduce the discount, and thus increase the profits for a particular title. Since the list prices are fixed, the retailer negotiates the discount, and as leverage over the publisher, gets to influence the placement of the book within the store. Each publisher is forced to compete with other publishers. These goals are also in conflict.
• High-Tech Equipment Manufacturer and Value-Added Reseller. A value-added reseller (VAR) provides solutions to end customers. They do this by combining products from manufacturers, and adding value – in the form of planning, custom engineering, installation services, etc. The VAR will negotiate a price with the end customer for a solution. The typical VAR sells products from multiple high-tech companies. The VAR will negotiate with the manufacturers to get the lowest possible prices from the manufacturers. The manufacturer wants the end-customer price (when it includes their equipment) to be as low as possible – to increase the number of sales that are made. The manufacturer gets the same profit (based on the price to the VAR) regardless of the end-customer price. Every dollar that the end-customer saves, the VAR loses in profit. The VAR makes profit on the difference between price-to-the-VAR and the final selling price. The VAR will also want to drive down the price it pays to the manufacturer. Reducing the price-to-the-VAR transfers profits directly from the manufacturer to the VAR. These goals are diametrically opposed.

When goals are in conflict like this, we can’t just relegate the “end user” goals to design inputs – we have to incorporate them into the prioritization process. In these examples, the “end users” are the VAR, the book retailer, and the automotive dealer.

Imagine that the high-tech equipment manufacturer sells networking hardware. The manufacturer has an internal (direct) sales force, as well as the VAR channel (indirect) sales force. The manufacturer identifies tools that help sales reps to close deals. Large purchases are commonly made at as much as 80% off list price. The list prices are irrelevant – they are not even guidelines in many cases. So the manufacturer develops tools to help sales reps know what prices to set for end customers.

Internal sales reps have generally well-aligned goals with principal stakeholders. The sales rep will be compensated based on a combination of revenue (sales) and margin (profits). This compensation model creates implicit alignment between the user goals (get a bonus) and the company goals (make profitable sales).

One approach to helping the sales rep close profitable deals is to share an indication of the profitability of the deal with the rep. The rep can (will!) set a price that is designed to maximize the sales rep’s bonus. If the compensation system is well designed – this is also optimal for the business, and therefore the principal stakeholder. The sales rep will get increased compensation for raising the price (and still closing the deal) by getting a percentage of the increase in margin. The sales rep is motivated to increase the manufacturer’s profits.

The VAR, however, should not know the profitability of a particular transaction. The VAR is motivated to lower the price (the price to the VAR) as much as possible – even at the expense of losing a “profitability bonus.” If the VAR is given a percentage of the increased margin (to the manufacturer) it comes at the cost of losing 100% of the change in price to the VAR. Remember, the VAR makes money on the difference between the price from the manufacturer, and the price to the customer.

Depending on the manufacturer’s business model, this could lower the priority of a margin-inspection capability, or dramatically raise the priority of features that restrict margin-viewing to only internal sales reps.

Also remember that the manufacturer and the VAR also have aligned goals – like closing the deal. And the VAR can close the deal with the manufacturer, or with products from a competitor. So the manufacturer is incented to provide valuable functionality to the VAR. The manufacturer cannot ignore the VAR’s needs, or the VAR will work with a competitor and the manufacturer will lose all the business.

You have to determine the value to the principal stakeholder of the value of the feature to the end user. In other words – even if a feature “hurts” the manufacturer, is the pain “worth it” because of the value of the relationship and expected future business that the company will do with the VAR?

Once the value of all of the functionality is identified, you can prioritize it. An enlightening way to visualize this value is with a value-delivery matrix. Thanks again to Roger Burlton for inspiring our approach to prioritizing based upon a combination of pain and gain.

We’ve written before about the importance of separating rules from requirements, particularly in use cases. We wrote that with the goal in mind of reducing the costs of system maintenance. Low-level rules like decision, calculation and inference rules tend to change frequently – and independently of other requirements. So a documentation approach that separates these rules from requirements can both reduce implementation costs (by encouraging separated implementation) and reduce the time required to manage and approve changes.

There are also benefits to abstracting high-level, or procedural rules, when dealing with global business requirements.

Global Businesses

When companies get large enough that they start operating globally, they face an additional level of complexity in managing their processes. And with that management burden comes the additional complexity of managing the software that implements those processes.

Global businesses usually don’t have the luxury of using the exact same processes, procedures, and rules in every company in which they operate. They also have to deal with nasty problems like selling a product from one country to a customer in a second country, with a delivery address in a third country. And the product may be shipped from a fourth country. Now imagine that the order is split to deliver portions of it to each of multiple destinations. And imagine it is further (orthogonally!) split because the products are being sourced from multiple locations. That’s a lot of complexity. How would you approach managing the requirements for something like that?

Let’s keep it simple and just imagine dealing with different processes and procedures in different countries. Global businesses usually organize around regions, like the Americas, Europe, Asia, etc. There are no formal rules to this organization, but the regional definitions are mostly consistent. Within some of those regions, there are often variations in how the business operates within countries in those regions. US Companies usually treat domestic US business differently than they would Canadian or Mexican operations – even on the same continent. And Europe, Africa and the Middle East have even more variation and distinct differences between countries.

Regional Growth

When companies grow into multi-national organizations, they don’t initially start in “every country” and then gradually grow all of the divisions in lock-step. Companies rightly focus on a single country until they are driven to grow into other countries. Then they establish footprints in those countries, grow those businesses, and eventually reach a size where they need to organize regionally.

The businesses in those countries and regions are usually given both guidance and latitude in the development of their businesses. As a result, the company will both develop new processes and extend existing processes into the new countries. Imagine a company like Caterpillar or John Deere that sells heavy construction equipment around the world. The company initially, likely, both manufactures and sells all of the vehicles in the same country. Then the company begins exporting vehicles to the other countries. Eventually, the business grows until the company sets up shop in the foreign country.

The company is now doing the same things in multiple countries (at a high level). Selling vehicles, leasing vehicles from a maintained fleet, financing purchases, etc. Consider the business of leasing vehicles – different countries have different cultures that approach borrowing differently. They also have different regulations about leasing versus sales. Our company may even decide to partner with a local third-party company that manages a fleet of lease vehicles for them in one country, while maintaining their own fleet in another country.

The people running these country-specific businesses have to react to local issues, regulations, and market dynamics. Success in those countries may require different operations than success in the home country. And the people responsible for these businesses are usually able to “do what it takes” to be successful in the different countries.

Global Processes

Now the company is faced with the situation where the same process (leasing a vehicle) exists in multiple countries or regions. At the same time, the process is different in each of the countries, because of the differences in how the business operates in those countries.

The company now has the same process defined multiple times. And that process is defined not only based on local influences, but also corporate policies, the policies that are in effect in the country where the company is based (and therefore reports income, etc), and those things that are common across the regions.

This means there is both variation and duplication in the process. And that creates opportunities for improvement.

Consider a use case that is part of a global process. For the vehicle leasing process, a use case (or sub-process) may be “Approve credit of lessee.” The company requires that all leases be made only to people who have been approved as credit-worthy. But determining credit-worthiness can vary by country. And the process required to determine credit worthiness will vary by country.

Variation by Country

Consider the definition of credit-worthiness. This is defined for a single country with a set of rules that represent the results of an actuarial analysis that does a risk-scoring process designed to weed out unprofitable loans. The credit-worthiness of a lessee in a third-world country would necessarily be different than the analysis in a major industrialized nation. And that means a different set of rules.

What about country regulations? There are different privacy laws in place in different countries. You may be allowed to contact character-references in one country, but not in another. You may have access to three years of records in one country, and seven years in another. These variations in regulation affect what you are allowed to do in the different regions.

And the businesses in different countries have evolved their processes independently over time. One business may choose to pre-approve a lease for repeat customers, while another country may require credit checks for all new leases.

These differences make the goal of globalizing processes and requirements seem insurmountable.

Why Globalize Requirements

There are many reasons to understand processes at a global level. Let’s look at just one. Reporting. Management accounting is the science (or art, if you ask a financial accountant) of inspecting measurable elements of your business so that you can make informed decisions about how you run your company. Being able to understand, analyze, and measure the same process in every country of the world provides benefits in strategic reporting and decision making. This consolidation can also be valuable for financial accounting and reporting of business performance for public companies. Making good management decisions is enough of a reason, so we’ll ignore the added financial accounting and external reporting benefits of a consolidation.

OK, so your construction equipment company operates in multiple countries. And you lease equipment in multiple countries. You want to know how profitable your leasing business is. Each country has developed different processes for leasing, with different rules for determining details like who to approve for a lease, and different calculations of profitability. For example, one country may monitor gross margins, another may track contribution margin. What about the rules for revenue recognition? One country’s business may recognize revenue at the time of signing a lease, while another may recognize revenue only when the payments are due (or when payments are made).

To get better control on your businesses, or more specifically, more consistent reporting, you need every country to follow the same process. Even though the “business” in each country needs to be handled slightly differently.

Consolidate Requirements

One approach is to take all 50 countries, analyze all 50 process variations, document 50 different use cases, and determine the proper reporting for each of the 50 situations. That’s a lot of analysis work. And a lot of risk to the reporting effort. You avoid disrupting the individual businesses, but you may make mistakes in any of the many analyses. And whenever any of the countries has a change in regulation, or when any of the businesses in those countries has a change in process or policy, you have to review and update your process, use case, and analysis for that country.

Another approach is to mandate that everyone follow an identical process – come hell or high water. This is completely impractical. For some countries, this will work. For others, this will force the businesses to operate at a competitive disadvantage (remember, there was a locally rational decision to deviate in the first place). And in the worst case, you may be “requiring” the business to operate illegally (or prevent it from operating at all) in some countries.

A third, more reasonable approach is to look for a common abstraction. Develop a description of the process and use case that applies to all of the countries, while allowing for a representation of the variations. This might encourage individual countries to make changes to their processes (in order to appear more consistent with the rest of the business), but it allows them to continue to deviate.

How is this possible – we’ve identified that each country has a different process, so how can the same process documentation be correct for the different countries?

Business Rules Provide the Abstraction

Most of the variations in process identified in the example above are really variations in rules, happening within similar or identical processes. Think of it from a use case perspective – here’s a snippet from the normal flow of the “Approve Credit” use case:

1. Lessee submits request for financing.
2. System approves lease per BR01, Credit Approval Rules.
3. Lessee confirms intent to lease.
4. System reserves vehicle.
5. …

The key is the abstraction of Credit Approval Rules. Even though those rules vary by country, all countries will follow the flow defined above. Note – this does not address the case when the processes are structurally different.

Then, within your business rules repository (or spreadsheet, or wherever you maintain the rules), you will have a ruleset (BR01) that defines when credit is approved and when it is rejected. What you can do is define different rulesets for different countries (or regions). BR01-USA, BR01-Canada, BR01-Mexico, etc.

When the business within a particular country changes its credit approval criteria, you only update those rules – and not the process or use case documentation. The use case remains unchanged.

In our calculate profitability example, you will need to either require the businesses to calculate the same way, or, because the data will be consistent, you can aggregate and report on the information at a global level – taking into account which transactions happen in what countries.

When Processes Are Structurally Different

What about when the process is significantly different in some countries? Perhaps the system reserves the vehicle in advance of qualifying the lessee (pre-approval of the lease)? We have a different process. Technically, it is a variation on the same process – the process would share the same name and have the same high level description. Only in the details would it be different.

We get to “make up an answer” here, I think – I don’t know of anyone who has standardized on a good solution for this problem. There are two reasonable obvious approaches that come to mind.
The first approach is to define multiple use cases, and organize them hierarchically beneath the original (global) version of the use case. If the use case is “UC01 Approve Credit”, then you would add “UC01A” or “UC01-USA” to reflect that this use case is a variation on the first one. Then you would trace the special case use case to the global use case.

This works, and minimizes redundancy, but it could be confusing to deal with this added complexity, in light of subordinate use cases, use case versions, and tracing of requirements. Would the requirement for “User submits application” be traced to UC01, or UC01, UC01A, etc.? You would trace to all variations for which the requirement is required. Each country-specific implementation team can then look at each use case and say “Do we use the global one, or do we have a special variation?” The team would then know precisely which requirements they had to implement.

Another approach would be to define the global use case – “UC01 Approve Credit”, and then for each country that has an alternative process, define an alternate flow through the use case. This takes care of the confusion with subordinate use cases and versioning. And it reduces the need for redundant tracing. But it makes the individual use case harder to read. And since most software today only traces requirements to use cases (and not individual steps in the use cases), it makes it harder for the implementation teams to know which requirements they have to implement for their countries variation.
Ultimately, we document requirements to foster improved communication. An approach that makes a use case harder to read (and approve), or harder to implement (or trace dependencies) is not as good as one that might make repository-maintenance more difficult, while improving the ability of the teams to understand both the contents and the dependencies of use cases.

Summary

Global businesses have variations in processes and use cases in the different countries where they do business. Documenting the individual processes leads to redundant documentation of requirements, makes it more difficult to analyze the processes (including reporting and accounting), and does not help in standardization of practices.

Abstracting rules, and finding commonalities in process patterns allows for consolidation of process documentation – which improves communication and analysis of requirements.

Utilizing alternate use cases to represent when individual companies or regions deviate from the global standard allows businesses to deviate their processes when needed, while minimizing the impact on making and managing changes to the processes across the organization. It also provides a framework for analysis, tracking, and encouragement of standardization of processes across a multi-national company.

Business rules are not requirements. Yet they are often gathered at the same time as requirements, from the same sources, by the same business analysts. And unfortunately, often documented in the same artifacts. In this article we look at some of the ways that business rules are commonly hidden inside use cases.

Separate Business Rules from Use Cases

As we’ve discussed before, business rules need to be separated from requirements. James Taylor and I continue to explore how best to isolate rules from requirements. To quickly summarize (and dramatically oversimplify) one of the points from James’ book, Smart Enough Systems, isolating the implementation of business rules allows you to update the way your business runs on your software much more quickly. And the first step to driving this isolation at the implementation layer is to isolate rules from requirements at the documentation layer.

Types of Business Rules

In our earlier article, we touched briefly on how business rules are used to define decisions within a use case or process flow. David Wright wrote an article, The Business Rules Approach, where he identifies five classes of business rules:

• Constraints – mandated criteria such as “the applicant must not be a felon”
• Guidelines – suggestions such as “the applicant should not have been rejected previously”
• Action Enablers – rules that initiate or trigger behavior, like “when the customer’s card has been rejected, it must be confiscated”
• Computations – the embodiment of calculations, like “pay 1.5 times the wager for a two-card total of 21″
• Inferences – the canonical “if…then” statements

These types of business rules can easily be hidden in different elements of a use case.

Where Business Rules Can Lurk

When we look at the structure of a formal use case, we see several areas where business rules can be hidden.

Description

Since the description acts as a summary or overview of the entire use case, any of the different types of business rules might be captured within it. Looking at an example from one of our old articles:

A pilot performs an FAA mandated list of equipment and operational inspections prior to every flight. All inspections must pass before the flight is allowed to take off per corporate policy.

“All inspections must pass…” is a constraint, and therefore a business rule. “Prior to every flight” is also a constraint. It would be better to write the description as follows:

A pilot performs an FAA mandated list of equipment and operational inspections [see FAA-1] prior to flights.

We’ve removed both business rules from the description, and added an explicit reference to the FAA mandated list. If the list of inspections defined by the FAA should change, we should not have to update our use case.

Triggers

Very often, these are action enabler rules. A trigger of “Student submits college application” is a trigger for the “Evaluate student application” use case. Although you could possibly argue that this is a business rule, there doesn’t seem to be much value in making the distinction. However, a trigger could also be “It is Friday at 5pm” for the use case “Process pending orders.” This represents a company-specific business decision to process orders at the end of the week. The order-processing use case would not change if the frequency were changed to every day, or every other week. The trigger really represents an implicit decision – “Is it time to process pending orders?” Using language that is more correct for a trigger, we would write:

It is time to process pending orders [See BR021, Order-processing time].

This would allow us to change the way our business operates more quickly. We could start processing on any frequency – or even start processing whenever more than 10 orders have queued up, or whenever outstanding orders represent $1000 in revenue (or profits). The key point is that by abstracting out the decision, Is it time yet?, we again can change how we run our business without having to update and re-validate the use case.

Preconditions

Business rules that represent constraints very often show up as preconditions to a use case. Since preconditions describe “what must be true” before the use case starts, this is understandable. Imagine we were writing a use case named “Process New Car Loan Application.” An obvious precondition might be that the amount to be borrowed has been resolved for the new car.

This would reduce labor, by only processing loan applications (which include running credit checks, etc), after a buyer has been locked in to a price, their trade-in value has been agreed to, and any deposit has been defined. However, this represents a linear process. An interesting business decision might be to immediately process a loan application as soon as the buyer agrees to start negotiations. The car dealer could use a conservatively estimated amount to get approval from the financing institution for a loan for “up to amount X.” Then, once negotiations have been completed, the only step remaining would be to fill in the exact amount and get the buyer’s signature. A much improved shopping experience for the new car buyer.

We could write this as follows:

A maximum amount for the loan has been identified [See BR033, Determining loan-application amount].

And then, within that business rule we can define heuristics like “Subtract Kelly Blue Book value of indicated trade-in from 5% below the sticker price” or use the average selling price for the particular model car + 5%, or any of a number of rules. Those rules can easily be changed without affecting the loan-application use case.

Normal and Other Flows

There are many opportunities within the normal course of a use case to hide business rules. Every point in the use case that could cause branching to an alternate or exception flow represents a decision. Each of those decisions represents the combination of one or more business rules. To be more precise, each decision represents a set of rules that are applied together to reach a conclusion (stay in the normal flow, or branch to another flow).

A use case named “Review conversation transcript” for a CIA analyst would have a normal course that probably documents that the transcript has been reviewed, and follows some archiving procedure. If the transcript identifies a “red flag” word or phrase like “Blackbriar” or “Touchstone”, then an alternate flow would be initiated. [Yes, I did watch the Bourne Ultimatum this weekend.] The trigger for this alternate flow could be written as:

3. Review of the transcript identified a red-flag word or phrase [See BR US-21744.6, Identification of red-flag words and phrases].

Then this business rule could be defined as a lookup into a database, it could be filtered – so that counter-terrorism analysts look for different words and phrases than people looking for drug dealers. This allows the “review a transcript” use case to remain stable while the rules for identifying onerous phrases are modified on a regular basis. This also allows the “review a transcript” use case to be changed without impacting the phrase-identification business rules.

Key Element

The key element of this reworking of use cases is to reference the sets of business rules that make up individual decisions, constraints, and action enablers. Those rules are maintained in separate documents. These other documents may be distinct documents, top-level objects within a requirements repository, or rule sets managed in a rules repository.

Most importantly, the rules are not hidden within the use case. Hiding the rules in this way makes it more difficult for developers to interpret the documents. It makes it all but impossible for the developers to abstract the rules into abstract decision services. It also slows down the approval process of the requirements and the rules – both initially, and when managing changes.

What is the right level of detail for writing requirements? What about for writing specifications (functional, non-functional requirements, etc)? The answer is that there is no one answer. But there are guidelines, and reasons to write more detail, or less detail – for any given product or project, and any given team. The reason we write requirements is so that they can be read. Understanding the readers is the key to determining which details to include in the requirements.

Requirements for Agile Teams

Steve Johnson and I had a great discussion this morning about his webinar from last week, Extreme Product Management. Steve’s presentation is really good, and worth a listen to answer questions about how to combine product management and agile development teams to achieve market-driven product successes.

As part of a follow-up, Steve and I got to talking about how much to document for agile teams. A few hours later, he shared a slide with me that he had put together, that provides a great visual of the concept. In short, the more your team knows about your domain, the less documentation details they require to be effective.

[click for larger version]

Generalizing The Relationship

Steve’s slide is well designed for the “who do we need to be effective with an agile process?” question. And it can also lead us down paths that consider outsourcing, in-sourcing, off-shoring and co-location of development teams. That isn’t necessarily where we want to take the discussion for this article.

What Steve’s slide (not from the webinar, by the way) illustrates is that different audiences respond differently to different processes. From an understanding of how agile processes work, we can extend this idea – we need to write differently for different audiences.

Generally speaking, the more you know about a domain, the fewer the words needed to convey a concept (or requirement) with precision. Without using jargon, you can still communicate more concisely. Remember, though – the goal is clarity, not brevity. For example, it is much easier to describe the concept of drafting when speaking to a racing fan. [Note: drafting is riding or driving close behind another competitor, in order to benefit from the reduced aerodynamic drag.] When someone already knows what drafting is, providing instructions on how to do it is easier than if they do not.

Use Case Details

At this point, you may be thinking but there is a right level of detail for use cases. Alistair Cockburn talks about the level of detail for describing use cases in Writing Effective Use Cases. Jeff Patton has a good article explaining Cockburn’s levels. Cockburn uses a metaphor of elevation:

• Cloud Level – very high level summary
• Kite level – summary
• Sea level – “single sitting” task descriptions
• Fish level – small tasks that add up to valuable tasks
• Clam level – very small details that make up small tasks

Cockburn suggests writing at three levels – summary, user goal (sea level), and sub-function (fish) levels.

The authors of Patterns for Effective Use Cases present an interesting pattern – EverUnfoldingStory (pattern 4.5, p102). They point out that different readers of use cases need different levels of detail.

An architectural analysis may only need very high level details of the use cases. Other readers of the use cases may need to understand the interplay of use cases at a more detailed level. And individuals may need to understand a particular use case in even more detail, while only needing a higher level understanding of other use cases.

The suggested pattern is to use multiple layers of use cases that can be “drilled down” into to get more detail, and can be rolled up (and hidden) to obscure detail when it isn’t needed. The clearest way to achieve this is with subordinate use cases.

This seems like conflicting advice – write for your audience, and write for all audiences.

Supporting Details

The language you use should be adequate for anyone who has a reasonable level of understanding of the domain. For example, in a business application, it would be appropriate to use language like “The system will report the net profit of the sale.” It would also be appropriate to specify a business rule that “All companies with EBITDA below 5% be treated as high-risk investments.”

When your team needs it, you should provide explanations and definitions in a glossary of terms. The level of domain expertise determines how much explanation you need to include. As a product manager or business analyst, you ideally should not have to document the definition of “net profit” and EBITDA. You aren’t teaching a course on financial accounting, you’re specifying a product. You should be able to reasonably expect that team members understand, or can easily find definitions for these industry terms.

You might need to define (or link to a definition of) HHI, or other more esoteric terms. You can’t expect your developers to have MBAs. You absolutely need to define any terms that are specific to a single customer (product managers cover your ears). For example, the method of allocating overhead. As a rule of thumb, management accounting terms would need definitions, as they are often interpreted differently by different companies. You have to find a balance, by understanding who is reading the documents, as to where you draw the line.

In practice, make sure that you have budget and time allocated to deal with this. When your company leans more towards the “development factory” model – treating people who sling code as a commodity, you will need to allocate more time and effort towards education. Recognize that you will be articulating business requirements, in a language that requires some understanding of business terms. If you can use that knowledge to influence how you staff the project, great. If you don’t plan ahead, you might get lucky – but more likely, you’ll find yourself with scope creep, or missed estimates.

How Have You Dealt With This?

I’ve been on projects where the implementation team had deep domain expertise. The communication was very efficient. I’ve been on projects where the team was able to very quickly gain that expertise. Those teams needed some early education, but very quickly became efficient. And I’ve been on projects with teams that had no experience in the domain. It was like teaching them a new language – and unfortunately, we did not expect to have to spend time on that education. And it delayed the project. Eventually, they became conversant in the domain.
The best practice I walked away with was to not clutter the artifacts (directly) with these definitions, but to identify and link to reference materials, and an easily searchable glossary of terms. This allowed team members to drill down when they needed to, without being distracted by wading through unneeded information when they didn’t.

We would love to hear about situations like this that you have run into, how they caused problems, and how you solved them. Maybe there are better ways to address this stuff.

We all know the story about the emperor’s new clothes. I’ve been thinking about prioritization and scheduling, and as far as I know, no one is promoting that we maximize value – they (and we) have been promoting that we do the most valuable stuff first. Doing the most valuable things first does not result in getting value the fastest. In this article, we show why not.

Genesis

About a month ago, I read an article by Kelly Waters on how to prioritize intuitively. He presents a magic square diagram, showing both the “how valuable is it” and the “how hard is it to do” axes. I’m oversimplifying, read his article for more details – he incorporates elements of risk, complexity, etc. I really liked that he was addressing the “missing element” of how much work is involved. However, his diagrammatic approach, while presenting this information very well, does not really yield insights into what to do first. Kelly and I had a great discussion over the next couple weeks, exploring the interplay of work and value in prioritization, trying to find a way to encourage value-maximizing decisions.

Prioritize By Value

We have talked about prioritizing the most valuable requirements first repeatedly. And in the last of those links, we accidentally hinted at, but didn’t grasp the real goal:

We will only consider those steps where the profitability of change exceeds our hurdle rate for investment.

We’ve also talked in the past about using use cases as the basis for scheduling, as each use case represents realizable value. For the rest of this article, we’ll talk in the context of scheduling use cases across releases.

Consider a very simple example – you have five use cases, with values of 10, 9, 9, 8, and 7 respectively (the units don’t matter). If you sort those use cases in order by value, from left to right, they would look like the following:

The size of each box shows the relative value of having the use case implemented.

Based on our previous guidance (and everyone else’s), you would implement them in order, from left to right. Makes sense. Do the most valuable thing first. Do the next most valuable thing next. Repeat until the value is not high enough to continue.

What About The Amount of Work?

OK, the amount of work required should play a role too. In our time-boxing article, we describe each release as having a given capacity, which you can visualize in terms of cost (resource) and time (duration of applying resources):

We fill up that capacity with use cases, based upon how much work is involved.

We can estimate the work involved with each use case by any of a number of methods – but the earliest estimates can be developed using use case points.

Consider the following “work” measurements, identified for each of our use cases from above:

We have the same sequence of use case implementation (based on value), but now we can visually see that there are different amounts of work associated with each use case. The area of each box represents the relative level of effort required to implement the use case.

Prioritize By Value Results

The best way to explain the flaw with the classical “prioritize by value” approach is to show what happens after the first release. Consider that you can accomplish 30 units of work in the first release.

We can schedule the first two use cases for this release. The size of the time-box above represents the amount of work that can be accomplished. With the first two use cases scheduled, the time-box will look like the following:

We have completely used up the available capacity of the team (Work = W = 30 = 10 + 20) by delivering the two most valuable use cases. We have delivered 19 units of value (Value = V = 10 + 9 = 19).

Value Maximization

When we consider both the value (V) and the cost (in terms of work, W) of each use case, we see that some use cases generate more value per unit of work than other use cases. If we consider the ratios of value to work (V/W), and sort the use cases based on this approach, we would see the following:

And with the previous specific value and work values:

If we were to organize our delivery of use cases based on this ratio, we would be saying “prioritize the most effective use cases in terms of value per unit of work.” This may seem counter intuitive, but it makes sense – get the most bang for the buck earlier, and you will get more value faster.

Consider what our first release would look like:

We would complete three use cases (using 25 units of available work), and we would deliver 25 units of value. We would also be able to start working on one of the use cases that would be delivered in the next release.

True Maximization

To find the mathematically proven maximal value, we have to do a bunch more work. This prioritization exercise is actually an example of the bin-packing problem, an np-complete computer science puzzle. To make a long story short, we can’t use a simple heuristic and guarantee that in all cases it will be optimal. But we can do better than “most valuable first.”

If we use the scheduling rule as follows:

Schedule the use cases in order based on the highest value-to-work ratio, skipping use cases that are “too big” for the current release.

Then we will get value out of the system as fast as possible. There are a couple problems with this approach:

1. It does not take into account that you can apply work from one release to a use case that is scheduled in a future release. Intuitively, any “remaining time” after scheduling complete use cases should be spent on the next highest-ratio use case. I haven’t proven that mathematically, but it makes sense.
2. Use cases, and their underlying requirements, and the implementation tasks to support those requirements are not actually independent. You may need to introduce one use case before another – the second use case may not be possible without the first one. Implementing a requirement that is shared across use cases will reduce the “remaining work” for those other use cases – causing a need to recalculate ratios. Implementation tasks are often dependent upon one another. The discrete tasks to support a valuable use case may require implementation work that is also leveraged in lower value use cases. Further, some implementation tasks must be performed sequentially. You can’t optimize a query before defining a database schema, for example.

The second problem actually applies to any prioritization approach that incorporates value. The nature of software development introduces constraints (X must be completed before Y can be started). Those constraints narrow the possible scheduling choices. And they make it impractical to determine the “optimal” solution. At least with commercially available tools, excluding expert systems, which can be used to solve this type of problem.

Conclusion

• Sequencing use cases based solely on value does not maximize the delivery of value over time.
• Sequencing those use cases based upon the ratio of value to effort will increase the rate at which value is delivered to customers.
• It is impractical (and possibly marginally valuable) to determine the optimal sequence for scheduling use cases to maximize value.

You should use the “highest ratio first” approach, and when a use case can’t be delivered yet because of interdependencies, skip it. Also – apply judgement to sanity check if you are doing something that seems odd – like delaying a high ratio, high value use case. Explore with the development team if there are ways to adjust their dependencies to allow for a “more valuable” delivery sequence

In About Face 2.0, Alan Cooper describes the elastic user as an ill-defined user who’s characteristics change to suit the needs of the developer – sometimes an expert and sometimes a novice. However, some of the otherwise good techniques for managing actors and use cases exacerbate this problem instead of alleviating it. How should we manage use cases while still getting the benefits of Cooper’s insight?

Traditional Use Case Actors

In our previous article on actor hierarchies, we showed a method of classifying users based upon their roles. For example, a simple hierarchy for people who drive cars could look like the following:

When defining use cases, you identify the primary actor of the use case. Secondary actors represent other participants of the use case, not other people who can act as primary actors. This introduces a problem with keeping track of all of the users who can perform a use case.

Action-based Roles

In More About Software Requirements, Karl Wiegers proposes the notion of having action-specific roles.

In Karl’s example, he presents a use case of “Request Chemicals”, with a set of users who may want to request these chemicals:

• Chemist
• Chemical Technician
• Stockroom Staff
• Lab Manager

Each of these four user classes can request chemicals from the stockroom. Karl proposes identifying the users above as user classes, with an actor role of Chemical Requester. This way, you can define a single use case, with a single primary actor – the person requesting the chemicals, regardless of what user class the actor is in.

This solution is designed for situations where more than one person could act as the primary actor. When designing for organizations that have more rigidly defined roles, this is probably most common in manager-subordinate situations. Subordinates will always do thing X, and their managers will occasionally do it.

The problem is that it treats the unequal users as being equivalent – making the elastic user problem worse.

Solving Both Problems At Once

There is an approach that will effectively address both problems. It builds on our initial attempts to combine interaction design and structured requirements approaches.

The first step in validating a solution to these problems is to make sure we are supporting the primary reasons, or goals of writing use cases. The three highest priority goals are around communicating the intent of what the system has to enable users to do. The reason for consolidating use cases to improve the efficiency of communication when all of the users have to do the same thing. So we want to make sure our approach uses a single use case.

The second step is in recognizing and addressing, rather than side-stepping a misunderstanding of use cases. A formal use case includes both primary and secondary actors. In our How to Read a Formal Use Case article, we clarify that the primary actor is not the most important actor (with secondary actors being other subjects), but rather that the primary actor is the subject and the secondary actors are other participants (like the system).

While it might be confusing at first, there is nothing to prevent us from having multiple primary actors. The naming is a little unfortunate and misleading (“Primary Actor”), but there is no reason that there can’t be multiple primary actors. Each primary actor is one of the subjects who can be following the use case. The Secondary Actors term is unaffected – it still represents the other participants in the use case.

When defining these actors, we should not use action-based roles, as Karl suggests. We should keep the user-role-based roles (chemical technician, stockroom staff, etc). To prevent the elastic-user problem, we should define personas that represent members of the user-roles.

The key to this approach is remembering that a given use case describes what users must do, not how users will do it. It is imperative that we avoid design cues in the use cases. One benefit of persona development is that you provide guidance to designers and developers in how they choose to implement to support a use case.

When Different Users Do It Differently

As a quick “what about…?” question – what if the different users have different things they want (e.g. – it is not an identical use case)? Variations in the use case should be handled as alternate flows through the use case, with the most common mechanism being the normal flow.

This is a slightly orthogonal problem – using action-based roles does not address this, nor does persona development. It can be a problem to keep track of which users use which flows. If the use cases are sufficiently different for different users, then the right answer may be to make separate use cases. And if you implement different flows in different releases, that introduces another problem. Neither of which is made worse or otherwise addressed by this approach. We’ll leave that topic for a different article.

From the Implementer’s View

With this approach, the developer and designer will see the following:

1. A use case, such as “Request Chemicals”.
2. A list of the primary actors, or subjects, of the use case (chemical technician, stockroom staff, etc).
3. For each user-role based actor in the list, there will be at least one persona that represents the relevant user population.

The designer can then design implementations of the use case that will be good designs for the persona that represent the primary actors of the use case. The designer may need to make trade-offs between expert and novice interfaces – but it is no longer arbitrary, it is explicit.

Summary

There is a challenge in designing user interfaces that incorporate the (personal) needs of the people who will be using the system. Personas are very effective tools for conveying an understanding of user populations that will result in good design decisions. We can associate those personas with the groups they represent through user-role based actor definitions. And we can map those actors to the use cases they perform. Allowing for multiple primary users of a use case, we avoid the need to duplicate use cases when multiple actors may perform the same use case – without undermining our solution to the elastic user problem.

In our ongoing exploration of how to meld the worlds of business rules and requirements, we look at an example use case and see how to extract the business rules.

Separating Business Rules From Requirements

In our earlier article we described one benefit of separating business rules from requirements. That article explored the benefit that we get from spending less time defining requirements and less time interpreting requirements. Ultimately, we spend less time developing our software as a result.

Business rules tend to be embedded in structured requirements artifacts because those rules tend to be uncovered during elicitation activities for the requirements. One very common and powerful artifact is the use case. And business rules often get embedded in use cases. We’ll look at an example.

Use Case Example

In Patterns for Effective Use Cases, by Steve Adolph and Paul Bramble, we find an example that shows several opportunities to embed (or more importantly, to abstract) business rules. The authors (there’s a link to the book at amazon at the top of this article in the Recommended Reading box) do a fantastic job of providing examples, both good and bad, that highlight behaviors common in use case development. It is a great resource, and if you are anything short of a use case expert, you should own this book.

Use Case 6.9, from p.160 of the book is a use case for withdrawing cash from an ATM. I’m retyping and editing it for our example – all mistakes are mine:

Name: Withdraw Cash

Primary Actor: Account Holder

Normal Flow:

1. User inserts his ATM card.
2. System reads and validates the card information.
3. User selects transaction and enters transaction details.
4. System validates transaction details.
5. User collects cash and withdraws card.
6. System updates the account and resets the system.

Finding Rules-Extraction Opportunities

The same normal flow from above is duplicated below, but with bold text to identify places where there is an opportunity to abstract business rules. We will look at each example.
Normal Flow:

1. User inserts his ATM card.
2. System reads and validates the card information.
3. User selects transaction and enters transaction details.
4. System validates transaction details.
5. User collects cash and withdraws card.
6. System updates the account and resets the system.

Looking at each opportunity…

• Validates the card information. What does it mean to validate the information? What information must be on the card? Possibly only the account number. Perhaps both the account number and an encrypted copy of the account number. Since a bank almost certainly maintains unique account numbers, and people’s names are never reasonably unique, the name of the account holder is redundant information – but it may be used as a redundant piece of information in a set of validation rules. Regardless, the validation criteria represent a decision – which is determined by a set of rules.
• Selects transaction. What is the set of possible transactions for the machine? That list of transactions may change over time. Are different types of transactions allowed for different accounts? While not an explicit decision – the list of transactions implies an implicit decision of what transactions the system must support.
• Validates transaction details. There will be validation rules associated with every transaction. What types of accounts can be used to transfer money to other accounts? What are the maximum and minimum withdrawal amounts? And do those vary for account holders (maybe high balance accounts allow larger withdrawals, or maybe account holders can restrict the withdrawal amounts for secondary card holders)? Each possible transaction will have a set of allowable actions / valid details.
• Updates the account. Perhaps service charges are made (or waived) based on a set of criteria. Maybe people with multiple accounts get free withdrawals. Perhaps the fees (charged by the machines) are paid by the bank and credited to the account.

Instead of writing requirements that specify these details, we should abstract out the rules (e.g. “See transaction list XYZ”).

Summary

[Ed: Added 2007-07-17, thanks Bengt for pointing out that this was missing.]

The requirements discovery and elicitation process uncovers both requirements and rules.  While not a formal definition, rules are “discrete requirements”, in that they should be managed differently.  Rules can be changed independently of requirements – the transaction-validation rules, for example, do not need to be defined in order to write the software, and should be easy to change once the software is written.  Rules may represent constraints, as Roger alludes in the first comment in the discussion below – such as regulatory compliance, or fraud-risk policies that are independent of the ATM interface/process design.  Rules may also be implicitly reflected, again, as Roger points out – such as a rule that requires an account to be verified prior to processing a transaction.

In all of these cases, the frequency of change, people responsible for the changes, or the impact on consumers of rules and requirements encourages us to abstract the rules from the requirements.

When you plan a release, agile user stories, or classic use cases are the best sized pieces to use in the planning – from the perspective of your customers. Each user story can be further decomposed into a set of specifications, and those into development tasks. Development tasks are the right sized unit to manage your work breakdown structure – communicating the release schedule internally with your development team.

Overview of Structure

Even agile projects benefit from having a structured perspective on why and how to develop the software.

• Customers have goals, and those goals have value.
• Those goals are achieved through user stories (or use cases).
• Capabilities, usually defined in a specification, enable people to execute the stories.
• Development tasks represent the work that must be done to implement those capabilities.
• Tests can be defined to validate the capabilities, and assure that code is working as-designed.

Scheduling Releases

We’ve written before about communicating a release schedule with use cases. The fundamental concept is that you need to deliver actionable, valuable capabilities with each release. Since customers get value from goals by executing use cases, you need to deliver a complete use case (or user story) for the customer to get value from it. This also helps with the “why do I care about release X?” question – because it provides value.

Although your customers don’t need to know which development tasks are included in what release, your team does. And as a point of clarification, when you are scheduling the work that fits in the time box for a release, you absolutely can schedule tasks that do not add up to a complete use case. Sometimes all of the work required to implement a single use case can’t fit within a single time box. And there’s no particular benefit to trying to force it to always happen that way. It is more important to schedule the most valuable use cases (or user stories) first. And then communicate to your customers the releases in which those use cases are completed.

Nine Development Team Benefits

Doug Blis, at Visionpace, just wrote a good article listing nine reasons to divide user stories into tasks. He provides a couple of paragraphs of detail on each of the following reasons:

1. Iteration Planning
2. Iteration Burndown
3. Accountability
4. Shared & Individual Learning
5. Tasks Encourage Better Design
6. Forecasting Velocity
7. Tasks Serve as Reminders
8. Talk to the Dog
9. What if you hear “can’t/won’t task?”

These are all excellent how do we improve as a development team benefits. Managing your development team’s efforts at the task level provides enough data-points to improve, without being so much work that it hinders. Tasks are also the perfect size for extrapolation and improved estimation on future projects.

Getting Bigger Picture Benefits

In addition to your development team getting better by using tasks, you can improve your overall software delivery process. The key is to be able to clearly define the traceability for the project. Traceability won’t really help the development team get better at developing (which may be why not many agile proponents talk about it). But it will help you manage your project, and therefore the release schedule for your product. And that allows you to improve your relationships with your customers.

Better forecasting of tasks (combined with traceability) yields better forecasting of capabilities. And this also leads to better forecasting of user stories (or use cases). This allows you to spend less time dealing with changes to the schedule – and more time focusing on finding huge value for your customers. And fewer schedule changes result in better relationships, more trust, and higher profit (when you can leverage that trust into higher prices, and when you avoid the costs of schedule changes).
Do it so your development team gets better. And do it so you deliver better products, and build better relationships.

Yesterday, we identified the high priority goal for the third release of nexus to be supporting creation of bundles of articles. In this article, we will define the use cases we need to support.

Defining The Use Cases

The first step in defining the use cases is to review the scope and vision for the product. Once we’re sure we’re operating within the scope, we review the goals of our personas, and then we define the use case names. The next iteration of the use cases is in the form of use case briefs. And finally informal use cases. This agile approach to use case definition seems like a lot of work, but the mechanics don’t take very long – most of the time is actually productive time spent thinking about the use cases. And the effort of writing a few things down introduces some implicit refactoring and editing. An analysis of the stakeholders at this stage will help identify any missing use cases – it helped us identify a missing one, as we’ll see below.

Scope and Vision Analysis

We reviewed the scope and vision yesterday as part of defining the goal for the release. The goal of bundles is to leverage the effect that the whole is greater than the sum of the parts to leverage articles from nexus to create valuable meta-artifacts that combine articles into cohesive collections, designed to achieve particular objectives. At a sound-bite level, people combine articles into bundles, and people will consume the collections of articles found in a bundle.

Persona Goals

We initially focused on Paul the product manager’s goal of sharing ideas, and started sketching out some design concepts based on how Paul might want to create his bundles. Those sketches helped keep us on target as we moved forward on use cases. From a classical requirements definition perspective, they were a bit of a segue. From an interaction design perspective, they were important embodiments of the ideas.

We actually missed a persona goal, until we did a quick stakeholder analysis. Until we reviewed the stakeholders, we completely forgot about consumption of the bundles – we had focused only on their creation.

All of our personas would be consumers of the bundles, with the possible exception of Brian the blogger, who is focused more on getting information out to others than pulling information in. Brian may be a bundle creator – he probably already creates summary-posts on his blog that collect multiple articles together. He can use bundles as a secondary means to organize his articles, or to combine his thoughts with others.

Use Case Names

The use case names we initially defined for the bundle-creators are

• Create a Bundle of Articles.
• Update a Bundle of Articles.

After reviewing the needs of other stakeholders, we added

• Study a Bundle of Articles.

Considering both the consumption and creation of bundles will definitely affect how we design the interactions and the implementation.

Use Case Briefs

Create a Bundle of Articles (Paul the product manager is the primary user, Jill the business analyst is secondary)
Paul defines the topic and a brief explanation of the goal of the bundle (to teach a new product manager how to write use cases). Paul creates an outline of the topics to cover in the bundle, organizing his thoughts and the topics. Paul then begins inserting existing nexus articles into the bundle at each point in the outline. Alternately, Paul may need to submit some articles to nexus in order to include them in the bundles.

Update a Bundle of Articles (Paul the product manager is the primary user, Jill is secondary)

Paul returns to an existing bundle, and adds new articles to it. Alternately, Jill adds an article to a bundle that she is studying to “complete” it from her perspective.
This raises an interesting question – should people collaborate on bundles? Or should it be single-author? I’m leaning towards collaboration, or an implementation that allows people to control it (e.g. make a bundle “open” for anyone to edit, or closed).

Study a Bundle of Articles (Jill and Ellen are primary, Paul is secondary)

Jill browses the available bundles in a particular topic area, and finds one that looks interesting. The bundle is a tutorial on how to write use cases for a project. She starts by reading the first articles, leaves nexus, and returns later. On each visit to the site she gradually reads the articles, occasionally rating the articles and providing feedback on them. Jill also provides feedback about ways to improve the bundle.

This use case would be greatly facilitated if there were a way to manually or automatically track which articles Jill has already read.

Stakeholder Analysis

Stakeholder analysis is important because it identifies who cares about a particular feature or functionality. It can be very effective for finding missing use cases – usually because of a focus on the indirect users of a product. For example, an accountant may generate reports with a product, which are then delivered to a regional manager. Although the regional manager does not use the software, her needs must be addressed when generating the report.

In the analysis of bundles, we initially overlooked the consumption of bundles. This was immediately obvious when we started to think through how they would be used. We went back and added the Study a Bundle use case. We also uncovered the possibility of a consumer becoming a collaborator on a bundle.

Summary

This analysis of use cases presents us with the inputs we need for designing the interactions, and defining the specifications for the bundles. The “under the hood” implementation will probably be very straightforward, while the user interface work will be more significant.

Prototyping.

Depending on which discipline is dominant in the project approach, the next step could be to define the functional requirements (or specification) that support the use cases. Or it could be to take user-centric approach to prototyping interface elements. Or it could be developing an understanding of the domain model that will drive the behavior of the site.

Functional Prototyping

Ruby on Rails (Rails, for short) makes rapid prototyping of the “under the hood” stuff appear to be very quick to develop. And Rails separates the presentation from the logic with a model-view-controller approach to code structure. From the reading I’ve done about Rails, the next step needed to get an interactive prototype is to define the representational model.

In the better object oriented programs I’ve worked on in the past, the underlying representation matches the user’s conceptual model as well as possible. This will be challenging to not confuse the two and expose the implementation to the users. I’m not sure what differences will exist between them, we’ll see when we explore this. Creating a UML static diagram of both will help.

UI Prototyping

Creating some mockups of the user interface and documenting some design elements and interaction ideas will help here. I started that process last night and have the first initial thoughts drawn on paper. I will scan those in and post them as paper prototypes.

Documenting Requirements

If we were using a purely structured requirements approach, we would create an SRS at this stage. In conjunction with this prototyping approach, we will capture those same requirements. The requirements will be defined in the context of the individual use cases that we are focusing on for the first release. Don’t forget to vote on the use cases if you haven’t already.

Iteration

This process will be iterative or concurrent. The goal is to get enough of an understanding of the design to create an initial prototype.

In our agile project case study we defined corporate goals and user personas, and from our understanding created a list of use case names. We refined those use cases into use case briefs, filtering out some of the use cases (for the first revision) narrowing the list to six use cases. In this article, we propose a prioritization of those use cases and ask you to vote to share your thoughts.

Use Cases

Here is the list of use cases that we’ve already defined, presented in what we think the priority order should be. Each use case lists the (primary & secondary) actors after the name of the use case. There appears to be an obvious separation of what to do first and what to do second. Each item also includes “first” or “second” in which represents scheduling use cases across releases. Each use case should be “completely released” within a single release (even if some of the functionality is quietly implemented during an earlier release cycle to make timeboxing more manageable).

Following the list is our thought process for proposing this order of importance. After that rationalization, we have three polls for you to vote on what should be included first. There are three identical polls to allow each of you to vote three times. We’re presenting the votes this way in order to allow you to express “passion” for a particular item – you can vote on the same item three times if you want (the results will be combined).

1. Browse An Area (Jill & Paul + Ellen). First.
2. Suggest An Article [Version 1] (Paul & All). First.
3. Rate An Article (Jill & All). First.
4. Search For A Topic (Jill & Paul + Ellen). Second.
5. Broadcast An Article (Paul). Second.
6. Comment On An Article (Paul & All). Second

Prioritizing The Use Cases

The first question is the chicken and the egg question. How can users browse without the ability to suggest? We put browsing first because browsing will happen much more frequently than suggesting. Note that version 1 of suggesting is the one we are prioritizing (user must submit the article through the site). Versions 2 and 3 are lower priority than the other 5 use cases here – if you disagree, please join in the discussion on this article and we will revisit.

Rating of articles follows immediately, because rating the articles makes browsing better, but you could browse without a rating. Ratings are placed ahead of searching because we think that searching is a “more is better” capability, where “rating” is one that is intrinsic to the nature of this site being effective. An interesting article from nForm on social networks provided some thought-guidance on visualizing the characteristics of a social network. Hat tip to Leisa at disambiguity for the reference.

Broadcasting slightly nudged out commenting because we think the ability to “market” the site will be more important when the site is first starting out – trying to reach a tipping point where the aggregate user contributions just “make it work.”

Voting To Promote Use Cases

Enter each of your votes here for the use cases that you believe should be in the first release (you may disagree with our analysis). If you want to share your thoughts, please include them in the discussion for this article – it may help convince others that your approach is better (getting more votes for your use case).

[poll=7]

[poll=8]

[poll=9]

Thanks for your votes, and if you selected “Other” – please explain in the discussion below. Note: I have placed two votes for Browse and one for Suggest – to show that I think browsing and suggesting are the most important use cases, and because I think browsing is more important that searching (which could work as an alternative approach).

Each of the use cases defined as part of our use case names post is described at a high level of detail here. The goal is to get a broad view of the domain for our project so that we can focus on the most important elements. This is a key step in using use cases in an agile project. We need to understand enough of the big picture in order to determine what is actually the most important. Then we will work on the more important use cases.

Pre-emptive Filtering

After reviewing the use case names, we can pre-emptively filter out several of the use cases for this stage of the analysis. If you feel that any of these should be included in the initial release, please comment in the discussion area of this article, and we will revisit.

• The “Promote An Article” use case – where a blogger promotes their own work for review or publicity will be deferred until after the general sharing of articles has been implemented. The first version of “Suggest An Article” will serve as a means for the blogger to achieve his goals – it will just happen to be suggesting an article that the blogger has written himself. Brian won’t mind, as long as any functionality is retro-active (and that would make sense anyway, if he were to discover that someone else had promoted one of his articles before he did).
• The “Article Mashup” use cases will also be deferred from the inital release. While we think this functionality may provide a differentiating hook and significant value, it make sense to wait. Each mashup will be a mashup of articles that have already been suggested. So we need to have articles being suggested before we can start collecting them into mashups. As of right now, this will probably be the most valuable feature to follow “article scoring” features. We’ll revisit of course – that’s just a hunch.

Use Case Briefs

Excluding those use cases that are filtered per the above. We’re using the use case brief format explained in this sample use case article. The actors are being identified in terms of the personas we identified.

Use Case Name: Browse An Area

Actors: Jill (Primary), Paul & Ellen (Secondary)

The user is exploring an area to see if there is an article that “jumps out” as being interesting. This could be an exploration of a new area – trying to get the lay of the land. It could also be simply browsing an area that the user knows well, to see if something new or interesting has been written lately. The need to “only read something really good” is reduced a little here – the mode of searching is semi-directed, idle investigation. This is the usage mode that is most likely to have people “stumble upon” an article and score it.

Question: Should the “what’s hot right now” mode of browsing be included in this use case? Think about the “watch the front page of digg.com” model – the area is our entire niche, not a section of it – but the idea is the same.

Use Case Name: Search For A Topic

Actors: Jill (Primary), Paul & Ellen (Secondary)

The user is looking for articles on a specific topic, and wants to read the best articles first (or only!). This type of searching would not neccesarily be constrained by topic area – the user may want to actively find cross-posted articles (for example an “agile” article on use cases). They key element is that the user wants to research a specific topic.

Use Case Name: Rate An Article

Actors: Jill (Primary), All (Secondary)

The user has just read an article found by browsing or searching. The user will provide a “recommendation” – should people make sure that they read this or skip it. The user will also optionally identify if they think this article is targetted at beginners or experts (is it an explanation of how parallel activities work in BPMN, or is it a discussion of how you can create deadlock conditions in a BPMN diagram?).

Question: Should rating an article require users to be logged in? Mainstream sites use this approach, which probably prevents the worst gaming of the system, in exchange for the potentially tedious step of logging in.

Question: Should users be able to “recategorize” articles if they feel like something was overlooked, or the article were incorrectly classified (e.g. had nothing to do with use cases, but was tagged “use case”)?

Use Case Name: Broadcast An Article

Actors: Paul (Primary)

The user will want to share a particular article with people who are not part of the community on the site. After optionally rating an article, the user will identify some people to email the article to. Those people are probably coworkers or former colleagues who the user believes will benefit from reading the article.
Email was suggested as the communication method, and we’ll use the term ‘email’ as a proxy for “tell non-users about an article” for now. This will be less cumbersome than jumping through hoops to avoid saying ‘email.’

Thought: This capability may also be used for other “check this out” goals – we should prioritize the “you should read this” goal when defining requirements / designing this functionality. Other goals may be identified in the future.

Use Case Name: Comment On An Article

Actors: Paul (Primary), All (Secondary)

The user will optionally add a comment or notation to an article after rating it. Comments are great qualitative feedback to help other users decide between articles that they find as part of searching or browsing – but it is “second order” feedback that helps someone refine their search. The “first order” feedback is created via the “Rate An Article” use case.

Thought: A secondary use of this capability could be to ask questions or develop a conversation around an article (eg “This Worked for Us” or “Had anyone actually done this?” Not all articles are published such that their authors encourage on-site conversations like this. Having this facility will help users, and possibly authors.

Thought: Requiring someone to have rated an article prior to commenting will help with spam.

Use Case Name: Suggest An Article

Actors: Paul (Primary), All (Secondary)

Thought: Brian is almost a primary user of this use case, given the filtering of Brian’s use case from the initial release. He would be treated as a supplementary persona for this use case – using functionality designed for Paul without modification.

The user has discovered a great article for our niche and wants to include it in the site for others to read and review. The user will add the article to the site and optionally rate it. The user may also specify the tags/categories for which the article applies, and may classify the article as being for beginners or experts.
Version 1: The first version of this use case will require the user to be logged into the site, and enter the URL of the article directly into a form on the page.

Version 2: The second version of this use case may allow users to use a widget (like stumbleupon, or other widgets created for other sites like digg and delicious) to suggest an article with less interruption to their other browsing.

Version 3: A third version of this use case may allow users to unobtrusively leverage other external activities to automate all or part of the submission process. For example, automatically submitting any del.icio.us articles with a specific tag, or allowing a blogger to “trackback” to the site and initiate a suggestion.

Question: Should users be forced to rate an article when submitting it?

Summary

This overview paints the domain of our project (as defined in the scope and vision article) with a broad brush. It allows us to take the next step of prioritizing the use cases.

In our agile programming case study, we have two corporate goals, but one of them (learn Ruby on Rails) only drives constraints, not requirements. The other goal is to make it easier for people to find and read great content in our niche. This makes the documentation of goal-driven use cases pretty straightforward. All of the use cases support this single goal.

With an understanding of the goals, the next step is to define the use case names.

Before we can do that, we have to revisit and re-organize our goal definitions.

User Personas Drive Practical Goals

However, we’re folding in some elements of interaction design by defining user personas, which means the hierarchy of support structure for our goals is a little different.

We defined four personas in our earlier article:

1. Jill the Business Analyst (Primary)
2. Paul the Product Manager (Secondary)
3. Brian the Blogger (Secondary)
4. Ellen the Program Manager (Supplemental)

Defining Practical Goals

These practical goals represent the role that each persona might play in achieving the corporate goal. There is a lot of overlap in what the different personas want to do, and that is further complicated by the context in which they want to do it. The ideas are really very simple, but describing them simply is complex. We looked at the needs of the different users earlier.

To bring things together with clarity, we will document the goals here, and parenthetically identify the personas that share each goal.

• Learn a Beginner Topic (Jill, Ellen)
• Learn an Expert Topic (Jill, Paul)
• Promote an Article (Brian)
• Share an Idea With Non-Users (Paul)
• Participate in Discussions (All)
• Score a Good Idea (All)

The last goal is more nebulous than the others. For some people, scoring an idea may be “the cost of doing business”, recognizing that it is the way the site works – ideas that are scored highly are easier to find. These people may see the scoring of articles they have read as their payment into the system, so that they can more easily find articles with great ideas (because other people score those). It is a communal dynamic.

Other people may simply score articles because it is a good thing to do – a for-the-betterment-of-all approach. This is easy to rationalize, because by raising the skill levels of everyone in our niche, we raise the value and visibility of the value we can provide to employers. And this increases demand for our services. This is very indirect, but intuitive. I honestly don’t know if this is a motivator for most people.

Here’s a quick poll – please let us know why (and if) you would score the articles on the site.

[poll=6]

Also, please note that we’ve used promote to imply promotion of your own article, and score to imply “promotion” or demotion of articles written by other people. This distinction will be necessary to clarify when we are discussing features to support Brian’s objectives.

Defining Use Case Names

The diagram above shows scenarios instead of use cases as the next step. From the referenced article:

The practical goals are an analog to the Wiegers goals – they represent the software-relevant goals of the company, in actionable language, associated with a particular persona (class of users). The association with the persona is the key element that allows for great design. The actionable nature of the goals may incorporate or imply particular business process design decisions (made outside of the scope of either process).

The main benefit we get from this approach is the ability to not implement the non-essential features. The absence of these fluff-features allows the most important users to master the software faster without having to deal with low-value complexity.

The scenarios are effectively the same as informal use cases.

Interaction Design and Structured Requirements

For this project, we will use use cases – it probably simplifies communication, and as the quote above mentions, the same objective is met. Each goal is listed again below (in bold), and the names of the use cases that support the goal are listed underneath it. A use case name is listed multiple times if it supports multiple goals.

Learn A Beginner Topic

• Create an Article Mashup
• Browse an Area
• Search for a Topic

Learn an Expert Topic

• Browse an Area
• Search for a Topic

Promote an Article

• Promote an Article
• Rate an Article

Share an Idea With Non-Users

• Broadcast an Article
• Broadcast an Article Mashup

Participate in Discussions

• Comment on an Article
• Comment on an Article Mashup

Score a Good Idea

• Suggest an Article
• Rate an Article
• Create an Article Mashup
• Rate an Article Mashup

Note that “suggest” is used to represent creating a link/entry in the site for a particular article written by someone else. Also note that “promote” and “suggest” may get combined if the Brian the Blogger persona ranks lower in the priority for the site. Or Brian may be able to use the “suggest” functionality to achieve his goals.

New Idea Introduced

As part of naming the use cases, we introduced a new idea – the idea of an “article mashup.” Think back to when you did research for a paper in high school (if you’re old enough) – you found passages in magazines and books from all over the library. You photocopied them, and maybe even stuck them all together in a binder and called them “research.” Then you referenced those articles from different sources when compiling your paper.

Now imagine if you could do the same thing, but make it useful for everyone else, and make it be easy!

You could have a mashup like “Intro to Use Cases” which included references to several articles about use cases – the ones that you found to be most helpful when getting started. All bundled together, put in order, and made easy for consumption by other people. These ‘mashups’ of articles can be pulled from anywhere on the internet, mixed and matched as you please. Since these mashups have a value beyond the sum of the articles included in them, they should also be rated and reviewed – just like individual articles. This may even be the killer feature for the site.

Did We Miss Anything?

Any of the user goals slip through the cracks?

Any use cases that you think we missed?

Got any feedback on the mashup idea?

People who are new to software, requirements, or testing often ask “What’s the difference between a use case and a test case?” This article answers that question, by building on earlier articles about use cases and use case scenarios. At the soundbite level, each use case has one or more scenarios, and each use case scenario would lead to the creation of one or more test cases.

Definition of a Use Case

Use cases tell the story of how someone interacts with a software system to achieve a goal. A good use case will describe the interactions that lead to either achieving or abandoning the goal. The use case will describe multiple paths that the user can follow within the use case.

Definition of a Use Case Scenario

A use case is made up of one or more use case scenarios. Each path that can be followed within the use case is a use case scenario. Any given example of following a use case also follows a single scenario. Multiple executions of the use case can use the same or different scenarios.

Definition of a Test Case

There are many different kinds of testing, and they can be described in different ways. They can be done by different people to achieve different objectives. They can be manual or automated. Testing is a very large field, and this article is not trying to define all of the ways that people can test software.

When someone asks the question “What’s the difference between a use case and a test case?” they are generally referring to system tests, “end to end” tests, or blackbox tests. They are probably not thinking about unit tests or integration tests.

Check out this explanation of the difference between unit tests and system tests. Or this article for an introduction to Continuous Integration – an approach to test automation and software development, or this article on the essential practices of continuous integration.
System Test Cases

Many system tests are designed to simulate how a user interacts with the system, to make sure that the system responds appropriately. If you’ve defined your requirements by using goal driven use cases, you can use the use cases as a framework for defining these test cases.

These system tests should be created to test a single situation. When using the approach of use cases and use case scenarios to describe requirements, a system test should test a single use case scenario.

In an example use case we recently wrote, one alternate flow “3A1″ involves the user entering shipping and billing information that is unique to the order they are placing. You would define at least one use case scenario that involves these steps. Assume that the scenario you have defined follows alternate flow “3A1″ but otherwise follows the normal flow.

You could create two system tests that are designed to validate that the requirements of the use case are met. The first system test would involve a user that has an account but elects to use different information for this order. This is a realistic scenario – perhaps someone is ordering a gift to be delivered to their cousin who lives at a different address.

You could also define a system test that involves a user without a pre-existing account.

Both test cases follow the use case, and both test cases follow the use case scenario. But the test cases test different things (from a business / requirements perspective). They may be testing exactly the same code, but from a system test perspective, you neither know nor care because a system test is a blackbox test.

Summary

A use case represents the interactions (or observed behaviors) associated with achieving or abandoning a goal. A use case scenario represents one of the possible paths through a use case. A test case represents one set of inputs that exercises a single use case scenario.

It is easy to mix up the definitions of use case and use case scenario. A use case represents the actions that are required to enable or abandon a goal. A use case has multiple “paths” that can be taken by any user at any one time. A use case scenario is a single path through the use case. This article provides an example use case and some diagrams to help visualize the concept.

An Example Use Case

Most example use cases are very simple. Unfortunately, a simple use case does not help get a clear understanding of the differences between a use case and a use case scenario. For this article, please refer to the sample use case provided in yesterday’s article.

This use case involves 17 steps in the normal flow, and three alternate flows that represent another 10 steps. The details of each step are provided in prose in the previous article. To understand the difference between a use case and a use case scenario, we can look at visualizations of the use case, drawn as a flow chart. As a reader commented earlier today, an activity diagram would be a “better” artifact than a flow chart. This is true, but this article will use flow charts, as they require no “additional” learning for most readers. Activity diagrams can be used, if that is your preference.

Diagramming The Normal Flow

The example use case includes 17 steps in a normal flow that involves the system being developed, and three actors (two of whom are other systems). The actors are the user, the fulfillment system, and the billing system. The actions of the system being developed are represented in the “System” swim lane. You can see that control flows from the user to the system and back again, and occasionally from the system to external systems and back again.

[larger image]

Diagramming Alternate Flows

The alternate flows can also be diagrammed using the same approach.

[larger image]

Each alternate flow is drawn in this example with different colored arrows (red, green, or blue) in order to present an alternative visualization of the flow of the use case.

Simpler Visualization Of A Use Case

The essence of the diagram, for the purpose of discussing use case scenarios, is the branching behavior. You can create a much simpler diagram like the following:

The normal flow is represented as a straight line from the solid black circle to the “END” object. Each alternate flow is represented as a curved line that breaks away from the normal flow. The “3A1″, and “5A2″ alternate flows return to the normal flow (bypassing one or more normal flow steps). The “5A1″ alternate flow returns to a step in the middle of the 3A1 flow. The “10A1″ flow has one or more steps that end in the use case being abandoned.

The colors have been added only to simplify the mapping of this diagram to the cross-functional flowchart above. If anyone knows of a formal name for this type of diagram, please add it in the comments.

Use Case Scenarios

The use case is represented graphically as the following diagram.

The diagram depicts every possible branch of the use case that might be executed in either the completion or abandonment of the goal of the use case. The use case may take any of the alternate flow branches or may follow the normal flow.
A use case scenario is a single path through the diagram.

This diagram shows the normal flow – one of the possible scenarios.

Another possible scenario would be to follow alternate flow “3A1″ and otherwise follow the normal flow. The simple diagram would look like the following:

Specifically, this diagram indicates the following path as shown in the cross-functional flow chart:

[larger image]

Finding All Use Case Scenarios

The next step is a somewhat mechanical exercise – identifying all of the possible use case scenarios for a single use case.

The user can take alternate “3A1″ or not, and then can take either “5A1″ or “5A2″ (in either case), or both “5A1″ and “5A2″, and then can either take alternate “10A1″ or not. This yields 12 distinct scenarios. You could arguably consider that taking “5A1″ multiple times is a valid scenario.

Summary

A use case defines all of the paths that lead to the success of the use case. The use case also defines all of the paths that lead to the abandonment of the use case without achieving its goal. Each unique combination of those paths that can be taken by an actor during a single “pass” through the use case is a use case scenario.