Stop. Drop. Roll. You remember the drill from elementary school, if you happen to find yourself on fire, Stop. Drop. Roll. Now don’t get me wrong, Salesforce.com is an amazing, fast, and nimble platform to make things happen for your business, but with great power comes great responsibility. As the system administrator, sometimes your answer is “yes”, sometimes it is “no”, and sometimes (and often) it should be “Let’s think about what you’re really asking first.”
I propose the following maxim: Stop. Think. Do. It’s easy to say “Sure, I can do that”, and then wire new functionality into your system, but did you stop and think about all of the ramifications, dependencies, maintenance, training, and things that can go wrong with your proposed solution?
Let’s put our Business Analyst (BA) hats on and dissect, the simple act of making coffee. Before you proceed any further, take a minute and write down how to make a cup of coffee with your favorite coffee machine. It probably goes something like this:
Fill the carafe with water, dump it in the machine, put in a new filter, add 3 scoops, push the red button, wait, pour, flavor to taste.
These are great instructions if you’re telling someone how to do something and they are familiar with making coffee. What you are not doing is building a process so that someone who does not even know what coffee is can understand it. You are making gross assumptions about the abilities of the user and all systems involved. Any breakage in these systems will cause a total failure because the weaknesses have not been identified, nor have contingency plans.
Here’s a few questions I’d ask regarding the coffee making process:
What kind of water are we starting with? (Tap Water, Filtered Water, Distilled Water)
What is the ambient temperature of the water?
What type of machine are we using?
Are we using bleached, unbleached, or screen filters?
What variety of coffee do we use?
Are we using whole bean or pre-ground coffee?
How much is a “Scoop?” Is it rounded or flat?
How long do we have to wait until the coffee is done?
What are we pouring the coffee into?
What substances, and in what quantities are we using to flavor the coffee?
How much do you stir the coffee when you put the flavorings in it?
What type of vessel do you use to hold the finished coffee?
And these are just unknowns about the materials and process when things are working properly! What about when things are not working properly, then what happens?
What happens if you turn on the faucet and no water comes out?
What if the water is contaminated?
What if you have no electricity in the house?
What if the coffee is expired?
What if you have whole bean coffee and your grinder is broken?
What if you have no filters left?
What if you drop the Carafe!
Making a cup of coffee is pretty forgiving, generally the process works. Sometimes it tastes good, and sometimes it tastes bad, but you still usually wind up with something resembling coffee. However, in Salesforce, or any IT project, when something “Tastes Bad”, it generally does not work at all. Instead of being in a gray zone, we’re stuck with zeroes and ones. If any step of the process is short of perfect, it will break the entire process.
So let’s try to make sense of the coffee making process from a simple Business Analyst tool called a Use Case. In short, a Use Case is a software modeling tool that creates a path of an interaction between system components with a useful outcome. Click Here to read the full wikipedia article.
A short overview of some simple use case terms:
Title: What is this use case called
Primary Actors: Who or what is involved
Level: What level is this use case directed to (Business process, user level, system level)
Main Success Scenario (MSS): Defines the path of optimal success
Extensions: What could go wrong, and how to address the issue
With this in mind, I’ll share one lightweight example of the coffee making process at a user level:
UC0 – Make the Perfect Cup of Coffee
Primary Actors: User, Coffee Machine
Level: User
Main Success Scenario:
1. User completes the following tasks:
1. Fill Carafe with Water
2. Get 3 scoops of Coffee
3. Replace Filter in Coffee Machine
4. Press Brew Button
2. Coffee Machine Brews Coffee
3. User completes the following tasks
1. Remove carafe from machine
2. Fill Coffee Vessel
3. Flavor and Agitate Coffee
4. Coffee Machine Warms Remaining Coffee
Extensions
1.1a. No water in tap
1. User sources bottled water and fills carafe with bottled water
1.1b. Contaminated water
1. User sources bottled water and fills carafe with bottled water
1.4a. User presses brew button but nothing happens
1. User checks electrical supply to coffee machine
2. User inspects coffee machine settings to assure everything is set to operate
etc. etc..
One note – bold text indicates a reference to another use case. So, filling the carafe with water could be its own use case with multiple sub steps, each sub step having its own set of extensions.
What is the advantage of documenting requirements in this format?
During my consulting practice, using this format of noting requirements has a few major advantages:
1. It is relatively fast (or should be). We usually collaborate through a first draft use case in 15-30 minutes. If it takes longer you’re reading too deeply into things.
2. It forces you to consider the interaction between the systems. Each use case step is one party adding to the dialogue and identify missing steps. In a development effort, a missing step could bring an entire project to its knees, blow budgets and time-frames and ultimately make a project fail.
3. It forces you to consider failure. No system is bulletproof. Each step always has an opportunity for a failure. These should be considered and reviewed. If an extension has a very complicated success scenario, you know that effort will be needed to mitigate the risk of this interaction.
4. Use cases are easily read by most developers. They are a great medium for communicating with other parties
5. Use cases work great as the beginnings of documentation and training materials. Hey, you’ve already outlined your business process and system interactions! Now just blow them out a little bit and add some screenshots of the finished product and you have instructions complete with failure scenarios!
A few final tips for use case writing and resources:
–The best use case is the one that actually gets read. With this in mind, don’t get too caught up in the form. Do whatever possible to keep it simple and yet still have enough detail to communicate the requirements effectively. This balance is often contingent on your team and their experience working with each other. If you’re outsourcing a large development project to people unfamiliar with your business, much more explicit detail may be required. If it’s for an internal project, you may be fine with a lightweight version.
–Use cases are always a dialogue. Each major step should be by a different Actor. If a use case step 1-6 is all user input, it is a one sided conversation not a dialogue. Combine 1-6 into one step, or add sub steps like above. The first word(s) of each step should be a reference to the actor.
–Keep it short. If a use case is more than 10-15 steps or contains multiple sub steps, it’s probably too broad. Break it up into smaller use cases.
–Steps should not contain the word “IF”. Use extensions instead to identify each condition and possible sub use cases. Using IF complicates the dialogue. Remember the Main Success Scenario is your optimal path where everything goes perfect. Therefore, any IFs should be considered extensions off of the optimal path
–Some extensions can be implied. If you’re using a computer, theoretically every step could have an extension “Computer loses power”. While it is worth addressing these global concerns, if they are being repeated over and over it may be overkill and does not help communicate the process.
–If anyone is seriously interested in this topic, I can’t recommend this book highly enough – Writing Effective Use Cases by Alastair Cockburn. Thanks everyone for reading, would love to hear if you have ever written documentation with Use Cases and what your results were, and if you have any tips to add to the above.
-Garry
