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:
- 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.
- The website keeps track of who “sent” the visitor.
- 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.
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.