A picture is worth a thousand words.  A prototype is worth a thousand lines of code.  Two key elements of product management – and of agile development are elicitation and feedback.  Low fidelity artifacts can significantly improve both.  Polished, codified prototypes can create problems that prevent you from getting the benefits of communication.

Prototyping Anti-Pattern

David Bernstein has three good quick-read articles about prototyping in the agile zone.  The first one depicts the primary anti-pattern of prototyping – mis-set expectations.

As I was walking him through the different screens I could see he was starting to get uneasy. As I talked I could see him becoming paler and tenser, as if he saw a ghost. After a while I asked him if he was ok. He finally said, “You mean to tell me that I just wrote you a check for over $100,000 for less than a week of work?”

Prototyping Caveat

The second article is quick reminder of one of the goals of a prototype.

The purpose of a prototype is to elicit feedback from others or verify a design approach will work. When doing this we generally only concern ourselves with the “happy path” through our code.

A Prototype is Not a Product

David’s third article explores a little more about the mis-setting of expectations, and provides a good parallel from the film industry.

Prototypes are rough sketches without the robustness of a final product and it is often confusing to users when we show them a half-baked version of their project for feedback, even though they know it is not yet finished.

Agile Prototyping on a Napkin

David’s advice is (good and) primarily about using low-fidelity prototypes to avoid disrupting the elicitation and feedback process.  Folks in the user experience community have known this for a long time, and adapted their processes accordingly.  Back in 2006, I wrote about prototype fidelity as part of exploring ways to use this insight in requirements gathering.  Prototyping, in particular, is a great way to elicit implicit requirements – those unspoken (“you should have asked!”) requirements that your customer or stakeholder assumed you knew, or didn’t think to tell you.

Multiple Levels of Interaction

David focused on the initial “will this approach work?” elements of getting feedback on a design – and by inference, some low-fidelity user acceptance testing that the proposed approach will meet your customer’s requirements.  Jan Miksovsky wrote an excellent article (also in 2006) that provides excellent guidance on how much fidelity to build into your prototype, depending on where you are in the design process.  This is important – the type of feedback you need at different stages of your design process varies.  Jan proposes that the first prototypes be rough sketches, just as David points out.  Jan goes on to show how and when to add additional fidelity to your prototypes (read Jan’s article to see his great visual examples).  Like I said, the user experience community has known about this for a long time.

Prototypes Are For Two-Way Communication

The key element, and the reason for creating prototypes, is to get two-way communication.  A prototype is not just a status update about your design.

A prototype is the start of a conversation.

[thanks uninen for the image]

Prototyping is not only useful for design conversations, it is critical to understanding your requirements.  Yes, a prototype will you get feedback about the design-execution of your proposed solution.  More importantly, a prototype can help you make sure you’re solving the right market problems.

Prototypes Are More Than Interface Mock-Ups

The first thing we think about, and everything you’ve read so far in this article, is about getting feedback on the user interface of the product.  Prototypes are also useful for gathering business rules*, understanding system complexity, and defining, clarifying, and validating requirements.

*In that article, I show prototypes as “not being useful” for gathering business rules.  At that time, I was thinking in terms of interface mock-ups only, not other prototypes.

Use interface mock-ups when you need feedback about user interaction.  Use other artifacts when you need feedback about other aspects of your product.  You can use prototypes as an active-listening technique when gathering market data too.  There are lots of ways to draw stuff to help with communication.

I’ve regularly used flow charts to prototype processes.  Within those flow-charts, which are initially prototypes of how the product will behave, are decision diamonds.  Those decision diamonds prototype the enforcement of business rules within the to-be-created product.  In the spirit of DRY (don’t repeat yourself), a quick polishing of your process diagram can serve as a persistent artifact of the requirements.  Just like a user interface mock-up.

In more complicated scenarios, I’ve also used UML statecharts and data flow diagrams to prototype behavior.

In the section on up-front planning in last week’s article on risk management and release cadence, I talked about the mental leap that people need to make to envision a product that doesn’t yet exist.  Prototypes are like big springboards that help people leap that chasm of imagination.

Important Safety Tip

Don’t use the wrong prototype (mock-up, flow chart, etc) for the wrong conversation or with the wrong stakeholder.  Showing when and where business rules are being enforced (in the process being designed) is great for getting feedback about your interpretation and potential embodiment of those rules.  It will be a disaster if you try and have this conversation with someone who is not the owner of those policies – like a representative user.  Sometimes, policies are “owned” by non-technical people who struggle to read diagrams.  You may have to walk them through how the diagram works.  They’re smart – they’ll get it.

Just remember – use the right prototype to emphasize the right ideas, and elicit the right feedback.

A picture is worth a thousand words.  Agile values working software over comprehensive documentation, and it values customer collaboration over contract negotiation.  With that in mind, how much is a picture of a model worth?  Check out a simple example, how it helped, and what we didn’t do.

A Complex Conversation

I was working with a client on an eCommerce website, where one of the things that was important to the client was having and managing an affiliate network that refers visitors (and ultimately customers) to the website. The conversations around exactly what the stakeholders of the eCommerce site wanted were pretty convoluted, and different stakeholders described the “requirements” differently.

Affiliate Network Background

An affiliate network can work in the following way:

1. When someone visits a website, and does so by directly clicking on a link on an affiliate partner’s page, the website is able to identify the affiliate partner who “sent” the visitor to the website.
2. The website keeps track of who “sent” the visitor.
3. If the visitor becomes a customer, the affiliate partner who sent the visitor is compensated.  One way to compensate that affiliate partner is by giving them a percentage of the revenue that the customer generates for the website.

This can be a lucrative model for both the eCommerce site and the affiliate partner.  The partner gets paid for funneling traffic to the eCommerce site, but not necessarily doing any other work (beyond what it takes to encourage people to go to the eCommerce site).  The eCommerce site gets increased traffic, at a manageable cost – proportional to the revenue generated by the incremental visitors (who would probably not otherwise visit the site).

Each business gets to focus on its core competency (sending traffic, for the affiliate partner; converting that traffic into revenue, for the eCommerce site).  The eCommerce site invests the majority of the time and money (probably orders of magnitude more investment), and the affiliate partner shoulders all of the risk, but can do this for almost no cost (if they want), in exchange for an uncertain revenue stream.  This blog is currently trying out an affiliate relationship with Carbonite – because I love the product (and therefore think people who visit Tyner Blain will too), and because the revenue generated, if any, will help defray the costs of writing and maintaining the blog.

Specific Complexity of an Affiliate Model

The complexity of this “simple” model becomes apparent when you ask a few clarifying questions.

• Will there be multiple affiliate partners?  (Yes)
• If someone is referred by multiple affiliate partners (on separate occasions), who gets credit? (The last affiliate partner who sends the customer to the site)
• Does the visitor have to purchase during the visit that was made from the affiliate partner’s site? (No)
• Is there an expiration date, after which an affiliate will not get credit for customer purchases?  (Yes, “N” days).  [Note: I am obscuring the actual value for this article, but N is a real number.]
• If a customer who was referred by an affiliate makes multiple purchases, for how many of them is the affiliate partner credited?  (One)

Asking these questions in different ways generated some different, and potentially conflicting answers.  The list above is the “after we put it all together” answer.

A Simple Model

We solved this problem by grabbing the immediately available stakeholders and pulling them into an office with a whiteboard for about 3 minutes.  [Ed: Our first article about using object-oriented analysis as part of requirements gathering is from three[!] years ago, this is not a new idea, and wasn’t then, either.]  I drew the following state transition diagram on the whiteboard, using an active listening technique, to confirm that I had consolidated the inputs into the right set of business requirements.  Documenting business rules with a state transition diagram was very effective at highlighting them.

Most of the explanations from stakeholders were in more of a use-case format, but a state-transition diagram was more effective at validating the rules and requirements in this situation.

The diagram above uses the following approach to describing the problem:

• Some customers are considered to be “actively referred” by an affiliate partner – and when that is true, an affiliate receives compensation for the order placed by the customer.  Other customers are not considered to be “actively referred” and no compensation is due to the affiliate partner.
• Customers can be “temporarily actively referred” and events modify that state.

What the diagram shows, given that context is the following business rules:

• When a customer is referred to the site, the “to be compensated” affiliate partner is identified, and associated with the customer.
• When the same customer is referred to the site by a different affiliate partner, the new affiliate replaces the old one.
• If “N” days pass after a customer was referred by an affiliate partner, that affiliation expires, and the affiliate partner is not compensated for future purchases.
• An affiliate partner is only compensated for the first purchase made by the referred customer.

The stakeholders that were present confirmed that this perfectly represents their business requirements.  Even cooler – a couple days later, the business person most-directly-responsible for implementing the programs came by, looked at the whiteboard, and signed her name on it to record her approval.  We also have a camera-phone snapshot of that.

What We Didn’t Do

I could have titled this article Mini-Model and Requirements, but Agile seemed more appropriate, because we didn’t go over the top with it (and it is a rapid-development, incremental project).  The diagram above also represents the minimum deployable version of the affiliate program for a given release.

We stopped short of creating the following diagram:

This diagram is more of a “classic” artifact that you would see in a BUFR (big, up-front requirements) project.  Our team collaborates regularly, and the affiliate program details were now relevant/timely.  We had the conversations, drew the diagram, confirmed (in about 10 minutes), took a picture, and shared it with the rest of the team.  There would have been marginal incremental value in making a pretty version of the diagram, so we didn’t do it.  Our goal is working software, not comprehensive documentation.

Conclusion

Just do what you need to do, then move on.  For our team, clarifying the intent was important.  Creating a formal, pretty picture added no extra value.  So we didn’t do it.

Business rules are often hidden in processes as hidden decisions.  Once you discover that hidden decision, how do you communicate the impact of exposing and managing the decision?

Hidden Decision

In our previous article on hidden business rules and enterprise decision management, we looked at a process that had a hidden decision.

First, take a look at the process with the decision still hidden:

Here’s the process (with the decision exposed) from that article:

The decision that was hidden was an implicit decision – “Pick One?” – for which the answer was always “No.”  After making this discovery, and communicating with your team, you then have to decide if you are going to make the decision explicit.  Making the decision explicit will involve defining the business rules for how to make the decision, and (if done in software) implementing the decision, or the ability for a person to make the decision.

Impact of a Decision

The diagrams above allude to the fact that there is money to be made in the process, in the “Continue Automated Process” step.  We need to provide a better understanding of how / when money is made.  A slight expansion of the process flow above (replacing the “Continue Automated Process” with a couple steps, looks like the following:

[click for larger version]

The last step introduces a real-world decision: “Sell products?” and only when the answer is yes does the process “Earn Revenue.”

If you’re analytically minded, you can apply percentages to each branch of each decision, and add everything up to figure out an answer.  That might be reasonable for a simple example like this one, but it can become too complex with a more complicated process.

There’s an easier way.  And since the goal is to communicate the impact to someone, you want an easier way.

Truth Tables and Decisions

A truth tables is a tried and true artifact for describing combined sets of decisions.  You can use it effectively to extract information from a decision-heavy process diagram.  Consider the following application of a truth table to the process above:

[larger version]

Each of the decisions in the process flow has a column.  Each row represents a unique path through the flow.  Each cell contains the result of the decision, for that path.  Note that when a path does not involve a decision, there is no value in the cell.

That provides a comprehensive view of the process, which you could build upon.  However, in this case, you are focusing on the impact of the hidden decision (“Pick One”).  The following paths, from the truth table, involve that decision:

[larger version]

Ignoring the other paths, and re-organizing, you find the following:

[larger version]

50% of the time, when “Many” results are found in the first decision in the process, if you pick one of the results, you will earn revenue.

[larger version]

When you do not pick one, 20% of the time, the customer (or user) abandons the process.  For the users that do not abandon the process, you earn revenue 50% of the time.  Taking both into account, you earn revenue only 40% of the time.

Adding Up the Impacts

When there are “Many” results from search, you can improve the performance of this part of your process by 20% – specifically, you increase revenue by 20%.  But only if you always “Pick One” of the many results. You can extend this analysis to determine the percentage of None/One/Many outputs from the search at the start of the process, and determine an overall impact on the process.  If search returned many results 10% of the time, you can increase revenue (overall) by 1% by always picking one of those results.  That gives you the business justification to calculate ROI on exposing the hidden decision.

The end result is that you have a simple way to communicate the impacts (truth table) in the language of stakeholders (ROI).

A business process is not just a sequence of steps.  A business process is a series of decisions and actions.  Some decisions are obvious and can be actively managed.  Some decisions are hidden, and until you discover them, you can’t manage or improve them.  Here is a real-world example of the discovery of a hidden enterprise decision.

Enterprise Decision Management

Over the past couple of years, I’ve collaborated with and become friends with James Taylor, an enterprise decision management guru.  He and Neil Raden wrote the book, Smart (Enough )Systems , you should get it if you don’t already have it.    It is sitting on my desk right now, and every time I pick it up I have to mark another page with a post-it note so I can find that good idea again later.  If you aren’t convinced, listen to this interview with James about their book.

James and I developed a presentation, Getting It Right: Rules and Requirements in Software last fall for the International Business Rules forum.  Below is a slideshare of a shortened version of the presentation, delivered to the Austin IIBA this spring.

A large portion of that talk was dedicated to discovering hidden business rules within use cases.  The reason we dedicated so much time to rules discovery is that the first step to managing decisions across your enterprise is to discover and isolate those decisions!  In this article, we will look at an example of a decision hidden within a simple business process.

A Simple Business Process

The following is a simple real-world business process.  The details of the steps in the process have been modified to clarify this example.

The process flow example above depicts an automated process that involves searching internal systems for an existing customer (record).  There are three possible outcomes from the search, shown above from left to right: no results are returned from the search, a single result is returned, or multiple results are returned.  When no results are returned, a new customer (record) is created, and the automated process continues.  When a single result is returned, that customer is used and the process continues.  When multiple results are returned, a new customer (record) is created and used, but the automated process is interrupted and a manual intervention is required before the process can continue.

This third path confused me when it was initially presented to me this way by the subject matter expert who explained the process to me. The business creates a new customer (record) even when multiple results are found because they don’t have time to determine which result is the right one, within the automated process.  They would rather create a duplicate customer (record), continue with the automated process, and clean up the mess later.  That’s much better than losing a sale (a very real risk because of delays due to manual oversight.

As part of this elicitation session, I applied a variation on active listening by talking to the diagram above (on a whiteboard) and enhancing it.

Impacts and Decisions

One technique that is effective in reaching agreement, generally, is to inspire the other person to “have your idea” so that it becomes their idea.  Once I understood the process above, I realized that there was an implicit decision in the process.  Instead of making the statement – “you have a hidden decision in your process” and then hoping the business stakeholder (also in the room) would care, I chose to start with the impact.  Presenting the impact of a hidden decision first might expose that decision and trigger acknowledgment of the hidden decision by the stakeholders.  The following diagram shows how I first modified the flow on the whiteboard.

The subject matter experts had told me that when there is a manual intervention in the otherwise automated process, the process is sometimes abandoned.  Imagine customers walking away from an online sale because (for some reason) the sale cannot be completed without an unexpected delay.  I represented this with the “Abandon Process?” decision in the flow.  This decision was never drawn before, because it is the customer’s decision, and it can not be controlled by the business.

I also pointed out that the business makes money only through the last step in the process, “Continue Automated Process.”  My goal was to accentuate that this abandonment decision has a very real value.  The stakeholder and subject matter experts agreed – this was something they had told me previously.  But they had never drawn it directly within their process.

As it turns out, this did not trigger any additional insights.  It did however, set the stage for describing the relevance of the hidden decision.

The Hidden Decision

After setting the stage, I updated the process flow diagram to expose the hidden decision.

The hidden decision is the decision of picking one of the many search results (top right corner of the diagram).  Your first response may be that the business is not picking any of the results.  My response is that choosing none of the provided results is a choice, just as picking any one of them would be.

This view of the process highlights that if the business could automatically choose a “best” result when searching returns multiple results, the business would avoid the risk of abandoned processes due to manual oversight.

With the current process, the business stakeholder acknowledged that the hidden business rule is ” pick none of the results 100% of the time”.  With current project schedules, there is nothing that can be done about that in time for the immediate software release (of the software that embodies this process).

Before our meeting was over, the business stakeholder added determination of future-state business rules to define the “how do we pick one?” decision to the deliverables for the next release.

A Smart (Enough) Decision

James and Neil (I would guess) will tell you that ideally, the decision (should we pick one, and which one should we pick) should be informed by the process.  A feedback loop can be created where we identify the customers (the people who might abandon the process), and determine statistically which ones are most likely to abandon the process.  For those people, it is especially important that we be able to “pick one” from a set of search results, thus completely avoiding the opportunity to abandon the process.  For those people who are unlikely to abandon the process, the “pick one” decision is less important.

If it were easy to “pick one”, we would consider changing the way search is handled to never return multiple results.  In this real world example, that is not an option (I’m intentionally not sharing the reasons, to avoid disclosing too much).  The only option in this case is for the business to respond intelligently (enough) when presented with multiple search results.

Conclusion

This process flow example has two primary outcomes – generate profits, or don’t generate profits.  The first modification of the process flow makes that possibility explicit.  That allows for an analysis to determine if there are any hidden decisions in the flow (there are) that impact the outcomes of the flow.  There may be other hidden decisions, but they do not impact the profitability of this process, so they were not explored.

We know to treat business rules and business requirements differently. One example – treat external government regulations as rules (because they are less subject to change than requirements). When you have multiple systems in an architecture, while “rules” makes sense for one system, “requirements” make sense for another. What do you do?

A Single-System Rules Example

Imagine you have a system that is responsible for calculating taxes on orders. Imagine that system is calculating VAT (value added taxes) in China.

After you analyze the regulations, you determine that the following rules describe what you must implement:

1. There are two groups of customers. General VAT payers and Small-Scale VAT payers.
2. General VAT Payers pay 17% VAT and will receive a Golden Tax invoice* (so that they may recoup their taxes later from the government).
3. Small Scale VAT Payers pay 17% VAT and do not receive Golden Tax invoices (because they may not claim a refund of those taxes).
4. All taxes must be calculated accurately (per product on an invoice, for a given customer) within 1 RMB per rules 1 – 3.

* A Golden Tax invoice is an additional piece of paperwork that, when required, must accompany the company’s standard invoice. This Golden Tax invoice is presented to the government to initiate the refund of taxes paid (and waived).

This is not the complete set of rules – I have simplified them for illustrative purposes, so don’t go implement anything based on this.

Your system receives invoices, updates them with the correct taxes, and returns them to the calling system. An invoice includes identification of the customer, and the products that have been sold to that customer. You document the four business rules above, and your developers implement a solution.

Given an invoice, your system calculates the taxes correctly per the four business rules. You’re done! Ship it!

A System As Part of An Architecture

Would that life were so simple.

How does your application communicate with other applications? Your tax-calculator has to receive an invoice without taxes, and return an invoice that includes properly calculated taxes. Your developers decide to implement your software as a service provider. The outside application passes an invoice, conforming to a defined schema, and the invoice is returned, conforming to a defined schema. Now are you done? Not quite. Who determined what is in the schema, and how did they reach that conclusion?

To illustrate the problem, consider this: Does your schema include a field for the invoiced customer that identifies if the customer is a General VAT payer versus a Small Scale VAT Payer? Or does the schema ignore that field, relying on an expectation that your software will somehow know, or somehow request that information from some other application?

The problem is, in an architecture – where any number of applications co-exist, someone has to determine who does what (in terms of the applications, not the people).

You can’t write a requirement that states “the invoice that is passed to the tax-system must include the customer’s VAT payer status.” You can, but you can’t do it until some design decisions have been made. Is that putting the cart before the horse? Design driving requirements?! No, it isn’t.

While the “who does what” decision is inarguably design, it is architectural design. And as such, while it happens before system requirements, it happens after architecture requirements.

In previous articles, with an implicit focus on a single application, we argued for a distinction between requirements and design, and described software development as being analogous to an onion. The architectural element adds a couple more layers to the onion.

• Market Needs drive architecture requirements (create invoices for customers to purchase products)
• Architecture requirements drive architectural design (one system creates invoices, another system calculates taxes)
• Architectural design determines the scope and requirements for a single application.
• Within the defined scope, the application’s requirements drive design.
• Continue into implementation and testing of the application.

[Note: Not shown, but just as important, is "end to end" testing of the architecture, across applications. We're skipping that to make a single point about architecture and requirements - but it is still critical, so don't skip it when executing.]

Requirements on Other Systems

Your tax-calculator application has defined an API that places requirements on the invoice-creation system. By defining that the API will include a “General vs. Small Scale” VAT Payer flag, you are placing a requirement on that other system.

This hints at one of the challenges of developing architectures. Someone has to determine if the current customer is a General or Small Scale VAT payer.

One (obviously poor) approach would be to ask the customer for every transaction what their VAT-payer-classification is. This is fine (and possibly even required) for first-time customers. But for a repeat customer who orders products every day, this would get tiresome for the customer.

Perhaps you have yet another application that just keeps track of existing customers. Your invoicing system is optimized for processing orders, not keeping track of customers. The architectural design decision is to maintain that information about existing customers, instead of asking the customer for every transaction.

Now you are starting to get some propagation of requirements.

• The tax-calculator system must know the VAT-payer-classification of each customer (to support rule #2).
• The architectural design sets the scope that the invoicing system must make the determination of a customer’s VAT-payer-classification. Therefore, the tax-calculator must be told what the customer’s VAT-payer-classification is, by the invoicing system.
• When invoices are created for existing customers, the invoicing system must get the VAT-payer-classification data from the customer-master application.
• When invoices are created for new customers, the invoicing system must record the customer’s VAT-payer-classification.
• The invoicing system must tell the customer-master application what the customer’s VAT-payer-classification is, for future reference.

Rules or Requirements?

When dealing with rules and requirements, this can be confusing. It is a business rule to account for VAT-Payer status when creating invoices (so that a Golden Tax invoice will be created in specific circumstances). But it does not look like a business rule to say that the invoicing system must tell the customer-master system the VAT-Payer-classification of each customer.

And that’s ok. It is not a business rule. It is a requirement.

Remember Traceability

The key to resolving this apparent conflict is to acknowledge that these other artifacts are requirements – and they are requirements that are needed to support the business rule. The business rule is dependent upon these requirements to be implemented – given the architectural design.

Remembering that this is a traceable dependency makes this easy to keep track of.

Remember Traceability

There’s another important reason to remember traceability. You need to know why the invoicing system must tell the customer master the VAT-payer-classification of each customer.

The architectural design requires the customer-master to keep track of the information. To keep track, the customer master needs to be told initially. The architectural design also requires the invoicing system to defer to the customer-master application for existing customers. And the architectural design requires the invoicing system to pass the VAT-payer-classification to the tax-calculator.

Design Before Requirements

Technically, yes, this puts design before requirements. But only architectural design – specifically, the allocation of responsibilities to each application, and the definition of how those applications must communicate with each other (or at least what information they must pass).

Some books on how to write and manage requirements mention using a glossary. Most books on requirements don’t go into enough detail about either the importance of a glossary of terms, or the precise use of the glossary of terms. Or if they do, they under-emphasize the benefits of a well-defined glossary of terms. Walking a day in the moccasins of a business rules analyst helps us all appreciate the importance of a well-managed glossary of terms.

Glossary of Terms

When I was first introduced to the notion of a glossary as a requirements analyst, it was explained to me at a very superficial level. To paraphrase – the glossary holds the definitions of the terms that people on the project might not understand. The intent was simply to provide a dictionary function – a place to look up the domain-specific and esoteric terms that developers or testers would find in the requirements. An easy way for people to know what the requirement is talking about.

A glossary of terms is much more than that.

A glossary of terms is a tool that provides the following benefits:

• Explicitly defines the nouns that are referenced in the requirements.
• Eliminates one of the many sources of ambiguity in the requirements.
• Is the foundation for other key requirements artifacts, especially a fact model.*

*A fact model will be the subject of one or more future articles, but for now, think of it as a model that defines the language used to express the relationships between business objects (nouns), as they are defined in the requirements.

It is worth noting that the glossary of terms and the fact model are critical to writing unambiguous rules – and after reading this article, if you aren’t convinced that they are critical to writing unambiguous requirements, then comment below.

Unenlightened Definitions

After attending the 10th International Business Rules Forum last week, I felt like I had been hit over the head with the “well, duh!” club. I knew what a glossary was, and how and why to use it. I never thought it was a big deal – so I never wrote about it. Now I know what I already should have appreciated about how important a glossary is to writing good requirements. I wrote the heading for this section, anticipating a review of some of my favorite requirements books – to see how they deal with glossaries. The treatments must not have been as insightful, or how could I have been so unappreciative for so long?

1. Managing Software Requirements, Second Edition. There is no mention at all of having a glossary of terms in this otherwise good book. And they even have an entire chapter dedicated to removing ambiguity from requirements!
2. Requirements by Collaboration. The best book on JAD sessions. This book has a good definition – “These terms serve as the foundation for all requirements models and business rules; the goal of the glossary is to provide a common vocabulary on which all of the stakeholders can agree.” However, this introduction has only two short paragraphs explaining what a glossary of terms is – not addressing how important it is. There is a good idea for running requirements sessions – to assign a glossary guardian during a session to record any business terms that crop up during the session.
3. More About Software Requirements. No mention.
4. Patterns for Effective Use Cases. No mention.
5. Writing Effective Use Cases. No mention.
6. Software Requirements, 2nd Edition. Ends a sentence in a paragraph on unambiguous requirements with “Define all specialized terms and terms that might confuse readers in a glossary.”

OK, enough bashing of my favorite books on requirements management (and they are my favorites). The point is, the glossary of terms is getting short shrift in the larger requirements community. Where other larger and smaller ideas get entire books, the glossary of terms hardly gets mentioned. If your favorite book isn’t on this list, chime in and let us know how it treats glossaries.

Glossary Gets Its Due

Business Rules Concepts, by Ron Ross, however, puts more emphasis on the glossary of terms. Ron starts by making a point of specifically defining the glossary as a glossary of terms – and provides this definition of “term” (via Merriam-Webster’s Unabridged Dictionary, 2000):

Term: a word or expression that has a precisely limited meaning in some uses or is peculiar to a science, art, profession, trade, or or special subject.

Ron goes on to spend a few pages emphasizing the importance of the glossary of terms, both on its own, and as the foundation for other artifacts that are critical to managing business rules. As we’ll see in future articles, some of these techniques will prove invaluable in managing requirements too.

Glossary of Terms

A glossary of terms, using the definition of term that Ron provides, is simply put, a list of all of the terms that represent specific nouns in the domain in which we are writing rules (or requirements). These are the subjects and objects of rules and requirements. They expressly represent relevant business concepts. Terms, by Ron’s definition, are always nouns. We’ll stick with that.

Every business term, however apparently obvious, should be considered. In two separate sessions at the IBRF conference by Ron and an employee of Ron’s company, Kristen Seer, Business Rule Solutions, we were exposed to some “obvious” terms that proved to be ambiguous. Here are a couple, plus some of our own.

• In baseball, what is the definition of “ball“? Is it a non-strike? A round object hurled by a pitcher? The game itself (“Play Ball!”)? Ron is famous for his baseball-rules examples.
• For an electric utility company, what is “load“? Is it the total power demand of all devices on the network? Is it the power demand of a single device on the network? Is it the minimum or average power demand over a period of time?
• Is a “customer” someone who might purchase products from us (e.g. someone to whom we market)? Or is a customer someone who has purchased in the past? Or is in the process of purchasing?
• Is “profit” measured net or gross? Is margin a dollar amount or a percentage? Contribution or total?
• Is “enrollment” what a student does for a class, or the count of all enrolled students?

The point is this:

Glossaries should include not only the esoteric terms, but especially should include the common and obvious terms that are subject to interpretation.

Imagine exploring the centralization (or possibly federation) of existing global, decentralized processes. Among other things, you are looking at the processing of sales transactions. And you are dealing with shopping carts, quotes, orders, and purchase orders. These different terms mean different things to different people – even within a single geography. And they evoke not only passionate opinions, but the interpretations (and misinterpretations) of these terms may have very sweeping impact on some high level decision making – beyond what they reasonably should. Do you want a glossary of terms now?

These terms, when undefined, introduce ambiguity into your requirements. You need to define them, and gain a consensus on the definitions. And you should reference all of the artifacts (use cases, requirements, etc) that use the terms (or reference all of the terms used in an artifact).

You can maintain a glossary of terms within your repository, in an excel file, a wiki, a word doc, or even a sharepoint list. The way your team interacts with these terms will dictate which mechanism is best. If you are managing requirements (or rules) in a repository, then a repository will probably be the best place to maintain the list – as it should simplify (or automate) the traceability between artifacts that reference the terms and the terms themselves.

Conclusion

The guidance we generally hear, to include terms that “might confuse someone” is right. It is also under-emphasized. Who would expect “customer” and “quote” and “margin” to confuse someone? If two people assume different definitions for those terms when reading your requirements, then at least one of them will be confused.

Don’t underestimate the potential benefits of maintaining a glossary of terms as a key component of your requirements development. Future articles here will present ideas that leverage the glossary of terms, and existing artifacts will get benefits immediately from the reduction in ambiguity.

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.

Each elicitation technique we have in our toolbox is a tool. But not every elicitation job is the same. If we have a hammer, we might be working with nails, or screws, or even an egg. In our analysis, we have to develop a deep understanding of our customer’s business(es). And that means we need to understand not only the goals and ROI, but the processes, rules, and requirements. Which is the right tool for each job?

Elicitation Techniques

The BABoK (Business Analyst Body of Knowledge) identifies ten different methods of gathering information. That list is a good one for describing the complete tool set that business analysts should have for elicitation. The same techniques are valuable for product managers too.

We wrote about those techniques almost a year ago, from a requirements gathering perspective. Check out that article for more details, but here’s the short list:

1. Brainstorming
2. Document Analysis
3. Focus Group
4. Interface Analysis
5. Interview
6. Observation
7. Prototyping
8. Requirements Workshop
9. Reverse Engineering
10. Survey

Different Views of the Business

Processes, requirements, and rules all represent different elements of how the business works, or how software must work to support the business. The most obvious distinction is one of perspective.
To oversimplify a little, some rules define the regulations and policies that constrain how a business operates. Some rules represent calculations, inferences, or enable actions that provide some precision about the business operates at a greater level of precision.

Processes represent a business design decision by the company. Given a set of goals and constraints (both “rule constraints” and practical ones – resources, costs, market forces, etc), processes are designed to achieve business objectives. They generally manifest as procedural instructions for the business. Note that they should be modeled at a higher level of detail than “open this file, walk down to purchasing…”

Requirements are an articulation of what a tool (in our case, a software product) must do when it is used in one of the business processes. The design of those processes has an impact on the requirements of the software. The rules that constrain the business (and by extension, the processes) must be enforced within the software.

Ultimately, we have to understand all three to create successful software.

Different Drivers of Change

A more subtle difference is in recognizing that processes, rules, and requirements change differently. Each class of artifacts changes for different reasons, on a different time scale.

Policy rules generally change as top-down mandates, or external forces. State or federal regulation changes can affect how a company does business. The Sarbanes-Oxley act has driven massive changes in how companies operate. These are relatively infrequent, but sweeping changes. Their effects cascade through everything the business does (and therefore everything that is required of the tools used to operate the business).

Decision rules generally change as part of feedback loops in processes. Consider the set of rules that an insurance provider uses for determining what premium to charge for a given policy. These rules are so extensive that they are maintained in rate tables, or other complex rules-calculation systems. An insurance company will have a department who’s responsibility is to maximize the profits that come from setting premiums. That means that they will tweak the rules in their rate table on a regular basis – like an ongoing science experiment. Predict, modify, inspect, repeat.

Process changes can happen as a result of policy changes, but more likely, they happen because of business re-engineering. This is the same feedback loop that affects low level rules, but on a grander scale. The big business consulting companies make very good money providing business consulting services. Part of that is strategic guidance, and part of it is process re-engineering. They look for inefficiencies and missed opportunities in processes. The predict the ROI of changing the processes, propose changes (maybe even help manage those changes), and repeat. These larger changes take more time than changing low-level rules.

Requirements articulate how the software must support the given processes, while implementing or enforcing the company’s rules. Requirements can change because of process changes, and policy rules changes. As long as you separate rules from requirements, then changes to low-level rules will not force changes in requirements. And ideally, for volatile rules, will not require you to modify (and test and re-release) your software. Requirements also change because they represent our understanding of the business’ understanding of what they wanted when we gathered them. And the business can change it’s mind, as it gets new data. One of the arguments for iterative development is that people don’t know what they want until you’ve given them what they don’t want. There’s some truth in that.

Effectiveness of Different Techniques

We’ve mentioned before that the same elicitation activities, and people, generally gather process data, rules, and requirements. And that presents one of the challenges in managing them independently. Here’s a table that summarizes the effectiveness of different elicitation techniques for uncovering and defining a business’ processes, rules, and requirements.

Each technique has a row, and is graded Consumer Reports style. Each type of artifact has a column. A full green circle means that the technique is well suited to eliciting that information. A half-filled circle means that you can use that technique to gather the data, but it is not as effective as the full-green-circle techniques. An empty circle means it isn’t impossible, but you should avoid it if you can.

As an example, reverse engineering is ineffective at defining any of the above. Reverse engineering can tell you what you have, but in no way can you assume that what you have is what you need. In fact, if it were, then your customer wouldn’t need to do the new project at all. Reverse engineering is a last resort that we sometimes have to rely on, but you should always treat it as a “starting point” – a baseline to be corrected and validated. It is certainly going to paint an incomplete picture – and often an inaccurate one.

And You?

These effectiveness assessments are based on experiences with dozens of clients in the enterprise software space, over a decade of elicitation. That means they are anecdotal. Thousands of people will read this article [Really. How cool is that?!]. So if you can confirm the above, or even better – correct it and share your experiences, we’ll be able to paint a much better picture. So – join in the discussion and let us all know.

Separation of business rules from requirements is a good thing. Not because of semantic distinctions, but because it allows you to write better software, write it faster, and change it more easily. This article is a response to an excellent comment on our recent article about hidden business rules. Thanks for challenging the idea – it either eliminates it from discourse or makes it stronger, and we all benefit. Here’s an attempt to make it stronger.

Goals of Separating Rules from Requirements

Writing software ultimately involves coding up an implementation that both satisfies the goals of the customers and enforces the rules by which that customer chooses to achieve the goals. This is the traditional way to write software – define the goals, and all of the enhancing, constraining, and clarifying details, then implement it. There are some inefficiencies to this approach, but they are in the “getting great at writing software” bucket, not the “avoiding failure at writing software” bucket. Consider this the medium priority goal of separating rules from requirements. In a Kano analysis, this is a more-is-better benefit.

When we set out to write software, it is with intent. That intent encompasses processes, rules, and requirements. The combination of all of these could be described as a summation of intent.

Maintaining software is expensive. When you design an implementation, you (should) think about what is likely to change when making your design decisions. The greater the probability or frequency of change, the easier it should be to make those changes.

Intent changes. Agile processes start with a premise that even if the true intent were fixed, our understanding of intent would change, as soon as we get what we asked for. In practice, both our understanding of intent, and the actual intent change over time. To make the language less cumbersome, for the rest of this article, when I refer to intent it is our understanding of intent – and changes to intent represent both changes in the true intent, and changes in our understanding of it.

When developers think about software maintenance, they often think about it in terms of bugs and features. What needs to be fixed, and what needs to be added (or removed)? To make a significant impact on the cost of maintenance, we have to take that perspective to the next level. Set aside fixing bugs (where bugs are “does not work per the requirements”), and think about the new features. The new features truly represent new intent. Or in an agile process, it may be the recently revalidated, previously identified, next most valuable intent.

In both cases, intent is a moving target, and changes in intent drive changes to the existing software. To minimize the cost of making those changes, our implementation should be structured such that the most common changes are trivial to implement – ideally, they won’t even require changes to the code. When you can change the behavior of an application without recompiling the application, you significantly reduce the effort required to define,develop,test and deploy an update to the application. And you can also dramatically reduce the time required to make the change.

This is the high priority goal of separating rules from requirements: increase the speed, and decrease the cost of changing software to match changes in intent. I’ll say it again in bold.

The primary goal of separating rules from requirements is to increase the speed and decrease the cost of updating software to match changes in intent.

While the cost reduction part of it is nice, it is the speed element that can be the most compelling. James Taylor and Neil Raden wrote about this in their book, Smart Enough Systems. We accept the premise that abstracting the implementation of volatile rules from the rest of the software provides benefits in speed of delivery on an ongoing basis. And that is the primary driver for the separation of rules from requirements. If you don’t accept that premise, then the only benefit comes from improved documentation style, structure, and standardization – all somewhat subjective benefits.

Visualizing The Benefits

Here’s a timeline showing the benefit of agility – being able to deploy and update faster.

The maroon curve represents “traditional” deployment – where the implementation of volatile rules is no different than the implementation required to support requirements. It will take longer to deploy initially (but not necessarily much longer), and it will take longer to make changes (when the rules have been changed). The upward sloping line starts displaying accumulated value as soon as the software is released. When the next iteration is released, the rate of value accumulation will go up. There is one iteration displayed in the timeline.

The green curve represents deployment with volatile rules abstracted in the implementation. This could be as low-tech as implementing field-level validations in a properties file (that is interpreted by the application), or as high-tech as integration with a rules-processing engine or service. This implementation begins accumulating value a little bit earlier, but at the same rate (keeping prioritization and other factors equivalent). The first iteration happens more quickly, so the slope of the curve increases earlier. The length of iteration has been shortened enough that a second iteration can also happen. This further increases the relative rate of accumulation of value. The longer this pattern goes on, the greater the disparity.

Encouraging This Behavior

Abstracting the rules from the requirements will make it easier for developers to absorb and design for those rules. Further, once the rules have been separated from the requirements, it is easier to identify which rules are the volatile rules. And that enables developers to make smart decisions about when to abstract the implementation, and when to embed it.

You could abstract only the volatile rules from the requirements, and leave other rules embedded within the requirements. There are three good reasons for separating all of the rules from the requirements.

The first reason is one of consistency of documentation, and arguably style. Your communication will be more effective when consumers of the documents know that all rules are treated in the same way. If developers have to look in the requirements for some rules, and a table of rules for others, they are more likely to miss something. Subject matter experts who are validating the rules will also be able to do that job more effectively when they are documented similarly.

The second reason is that by separating all of the rules, you will better be able to identify the ones that are volatile. You can more easily evaluate the rules as a whole, and formally or informally characterize their frequency and likelihood of change. The rules for management of available products and the calculation of risk in a portfolio are likely to change frequently. The rules that represent FAA regulations are likely to change infrequently. You can better assess this data when dealing with a cohesive set of rules.

The third reason is that separation of the rules will imply to developers that they should at least consider separation of the implementation. Especially if, in your documentation approach, you identify which rules are volatile.

Conclusion

There are differences in rules and requirements. While the content of how they are used when developing software may be only semantic, there are practical benefits to separating them. Separation of rules and requirements in a documentation approach will make it easier for your development team to implement solutions that separate volatile rules from the rest of the code.

And this separation will make the software more valuable, more quickly.

The 10th International Business Rules Forum is coming up fast in October 2007. Scott Sehlhorst and James Taylor will be presenting Getting it Right. Rules and Requirements in Software on Thursday at the conference. The articles on rules and requirements that he and I have been publishing on our blogs for the last few months are leading to this presentation. The IBRF has graciously offered a 10% registration discount code to readers of Tyner Blain. Read on to get it.

Getting It Right

James and I have been exploring ways to write about the interplay of rules and requirements for a few months. When you develop software for a single company, you start by gathering “requirements.” What you gather ends up being both requirements and rules. And there is value in teasing the two apart, managing them separately, and implementing them separately. Our presentation addresses this distinction, and some benefits and means of separating the two.

When you are creating “multi-customer” software, you need to be just as aware of rules vs. requirements, because you need a plan for allowing different customers to incorporate their (specific) rules with market-driven requirements. And for some applications, there are rules based on industry standards and regulations. You will benefit from abstracting these from your core requirements (and implementation), making you more agile than your competitors when responding to changes in those rules.

While geared more towards business analysts (because single-company development is more rule-centric), there’s value for product managers as well – admittedly more for companies selling enterprise software. Our presentation is on Thursday Oct 25th. James is also presenting Business Rules, Decision Management and Smarter Systems, with Neil Raden.

Here are the abstracts of our presentations:

• Getting It Right. Rules and Requirements in Software
• Business Rules, Decision Management and Smarter Systems

You can get the full schedule & abstracts (and printable registration) in this pdf.

Registration

You can register for the conference here (or by phone, fax or mail).

When you register, be sure to include the promotional code from Tyner Blain – 7PGRSP – getting you 10% off registration [Note: we do not get any referral fees or anything]. If you do sign up, or if you are already registered, send me a note (email at the bottom of the page) – it would be great to meet up with readers while at the conference.

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.

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.

We’ve written in the past about why it is important to gather and manage requirements. In short, you avoid some costly mistakes, and fix others before they become too expensive. We’ve also started exploring how business requirements and business rules live and play together. But why should we bother to separate business rules from requirements? One reason is to increase your company’s agility.

Benefits of Separating Business Rules

There are some significant benefits to separating business rules from requirements, and we learn many of them in our interview with James Taylor from a couple weeks ago. James’ new book, Smart (Enough) Systems, focuses on the benefits of automating decisions, but some of those benefits can be achieved to a lesser extent, just by isolating the business rules that would then ideally be automated. The main benefit that comes to mind is the increased agility of the company when it comes to changing their rules and processes. By isolating the business rules, they become easier to change and manage.

David Wright recently wrote an article at RQNG titled The Business Rules Approach. In it, he also points to the speed with which a company can change rules – not only as a benefit of managing business rules separately, but as a need to adapt and respond to today’s markets.

How Is Agility Increased?

There are two main ways in which agility is increased when separating business rules from requirements. First, the requirements management process will take less time. Second, the company can implement changes to their solution more quickly.

Less Time Managing Requirements

One best practice in writing requirements is to write concise requirements. You can’t just write the requirements with fewer words – that might lead to ambiguity. But you can dramatically simplify the writing, reviewing, and interpreting of requirements by isolating the business rules that represent decisions within a requirements document.

As an example, a process flow might include a decision – “Do we have the needed paperwork to approve the loan?” And that decision might represent a series of rules:

• If the applicant’s credit rating is above 700, we only need a valid driver’s license and SSN.
• If the applicant’s credit rating is between 600 and 700, we need a recent credit check, driver’s license, and SSN.
• If the applicant’s credit rating is below 600, we need a cosigner on the loan.
• If a co-signer is required, the co-signer’s credit rating must be above 600.
• If the applicant’s credit rating is below 600, we must run a new credit check, and have a valid driver’s license and SSN.
• If the co-signer’s credit rating is below 700, we must have a recent credit check for the co-signer, as well as a valid driver’s license and SSN.
• If the co-signer’s credit rating is above 700, we only need a valid driver’s license and SSN for the co-signer.
• If a recent (within 6 months of application date) is not available, a new one must be run.

In a process flow diagram, we could create a series of decision boxes – always requiring the applicant’s SSN and driver’s license, sometimes requiring a credit check (and some of those times requiring the credit check to be new), and sometimes requiring a co-signer. We would then have more branches for the co-signer.

This flow diagram would be pretty complicated. This can be simplified by embedding a decision tree into the requirements documents. However, you still are applying the (potentially) heavyweight requirements approval and validation process to this decision tree. You are also asking your developers to review this decision tree and determine how to implement it. A great developer will see when it makes sense to abstract these decisions from the code, and a less-great developer will embed them. In either situation, you’re asking your developer to spend time thinking about this abstraction – and thinking about how mutable the particular decisions are.

As an analyst, you are better informed about the mutability of the decisions. By documenting the decision as a single decision in the requirements document (“Do we have the needed paperwork?”) that references the enumerated business rules. It is also easier to review the rules and validate them when they are isolated. Business people who don’t have backgrounds designing software do find it easier to review these steps when presented in the context of a decision – and it is easier to grab the context of the decision from a simpler process flow diagram.

Less Effort To Change

Even if you don’t automate the decision, you still make it much easier to review changes. If the thresholds change from 700 and 600 to 650 and 550, it is trivial to update the isolated business rules. It is also an easier process to approve those changes when you are only updating and reviewing the business rules – and not a broader requirements document.

Developers abstract “magic numbers” like 700 and 600 (in this example) into variables and constants when they embed them into code. We are doing the same thing by isolating the business rules from the requirements (which then reference the rules).

What about changes that are more structural in nature? Imagine that we redefine the criteria – eliminating the 700+ rules, and changing the 600 rule to 650 – and always require a new credit check for co-signers. Then we also decide to add a new document – say proof of residence, or proof of employment. If we were managing this within our requirements document, it would take extra time to validate – and possibly re-implement the solution. With a solution like James proposes in his book, the business analyst could make the changes directly into the rules-processing engine and the software would not even need to be modified. In either case, the approval and change process is faster.