How and why to document Business rules (and Use cases)

Business rules are, I think, not given enough consideration in the projects I come up against. I'm a bit of an itinerant member of smallish teams and regularly see teams short on resource and time. Often I hear people speak of "business rules",  and nearly every project I've been on I've not seen anyone documents them.
Perhaps they don't need documenting. I think they do.

In my most recent contract one project had an incredible amount of Business rules. The task of the project was to replace an old system and set of accompanying processes with a new set. Most of the Business rules were to be in an "expert system" to do with qualifications, grades and occupations but there were many outside of that. The expert system was techie and geekie and obtuse but it documented the rules via the application's UI so they were taken care of, almost by accident. The rest were stumbled upon, discussed in emails by people who didn't know for sure, and either forgotten or if we were lucky, a code change was made to support it. Either way the rule was lost either in code or the fog of the project. And this continued for years.

The project team was under-strength and spread over three locations, business analysis was inexperienced and absent for some months, and the project was far more complex than anyone really expected. For my sins I came into the project after two years and immediately struggled. After my first eight months the first major phase was working. Which is ok I suppose. I'm only saying this as an example. It's an example in the general sense and to a lesser or greater degree it is common.

The general picture of the development and project process in this example would be to say that some of the developers wanted a Scrum approach but other developers distrusted this and management certainly distrusted this. So Scrum was replaced by a version of nothing in particular. This is pretty common too. So what could have happened at the beginning to have made it all smoother?
The objective for the process at the beginning of the project was to let the Business knew what they were letting themselves in for as the foundations of the project were being laid and details being discovered.
What is it that we are really going to be building?
What changes is this thing going to make to the business processes, to the people, to the productivity, to the service? Oh and how many people will be needed to get this all done and how long will we have to wait?

The way not to do this is to get inexperienced people to document the requirements and blame them a few years later if it goes titsup. What not to do after this is to get all excited and give it to the developers, stand back, and wait for the first delivery.

The Scrum thing will not work here. What we should do is think about the business processes. What is it that the Business is doing and how will we change that. There are ways to document this and be all professional (BPMN see bpmn.org). But if you are without a BA a quick google can help. Something is better than nothing. A flow chart, a list of processes in MS Word is a great way to frame the problem domain. The Business Domain.

But this post is about BusinessRules. So where do they come in?

For me they come in alongside the Use Cases, or User Stories. Quite often a User Case or Story can be a Business Rule. For example, A Business Rule could be that we send a summary of trades to the Ombudsman within 20 days. This could also be a Story, As Compliance Manager, I must send the summary of trades to the Ombudsman within 20 days of the request.

However, it may be slightly different. Perhaps the story / requirement will be for a configurable date or alerting system.

Also, Business rules may define the data being held on a customer, and when it must be deleted for data-protection regulation purposes.

For me, the huge benefit of use cases is the fact that they describle, in easy terms, how a lump of work is done. A process. A small process. That is the business and that is what out work is going to support. Starting with declarative technical requirements such a the "the Save button must confirm the user is saved in the database before saving the data." is so abstract and difficult to communicate to a non-technical business user in a project meeting. They must be good for the development team a bit later on, maybe in a work unit, a task detail, but not in a 100 page requirements document.

How to start with Business rules

I always create a document with a few sentences explaining why the document exists, and then I put a list of Business Rules, and then Use cases.

The only important rules I apply to the writing of business rules is:

The rule is not dependent on nor refers to any technology or system. The rule should be equally valid if the business was being run using a pencil and paper.

Rules should be grouped into easily understandable and relevant groups. And each Business Rule should have three fields:

1. An ID (can be a number or a letter and a number). The letter can relate to the title of the group of the rules. If  a rule is in a group entitled Refund Business Rules, then number the rules R1, R2, R3...
2. Business rule name, one to 4 words in length
3. A short description of the rule. 

Rules can be things like:

• what bits of data are mandatory, 
• what bits of data are to be removed.
• Trading days,
• Compliance issues.
• Regulatory points.
• Welfare issues
• ...

Question the norm in the dev team

 Apologies but it's a bit pompous of me using Einstein in the same post as my work, but here goes.

"Concepts that have proven useful in ordering things easily achieve such authority over us that we forget their earthly origins and accept them as unalterable givens." - Albert Einstein. 

It seems to me that software development generates a lot of acronyms and methods all providing the definitive in wisdom. As you get longer in the tooth you get cynical and question these saviours. Einstein was on a totally different level of course but the principle is worth thinking about in the development team.

The Planning Fallacy

Do we all experience the Fallacy on our work:

• Overoptimistic in the time planning therefore underestimating time taken.
• Overestimating the benefits

In 1979 a paper by Daniel Kahneman coined the term the Planning Fallacy.

It is a very real and measurable effect. Using a number of different subject areas from origami to tax returns. The tendency is to plan on the light side. Interestingly this only happens when we estimate our own work. When people uninvolved in the work are asked for estimates, they tend to over estimate.
No one really knows why, but vocalism is thought to be a candidate.

One curious observation is that people still tend to underestimate the task even if they have evidence from previous similar tasks.

The Given, When, Then - User Story Scenarios

In a previous post I talked about User Stories. This post is the next step on from there, and a way to evolve the User Stories into Scenarios.
As useful as this stuff is, it is often not used.

The relation between Stories and Scenarios 

A User Story will contain one or more Scenarios and the Scenario describes how the Story is used.


The Scenario Recipe
These are the three ingredients to writing a Scenario:

1. Given a context and set of circumstances
2. When something happens
3. Then the outcome is

Given <one or more contexts here> when <something is done> 

then <the outcomes go here>

Some examples
The following examples start from a User Story, which is where they should start of course.

User Story: Refund on a wheel
As a customer I want return a purchased wheel so that I can get a refund.

Scenario #1

Given I am a Platinum user and I have purchased a new wheel, when I wish to return the wheel within 30 days of purchase, then I can do so without a penally.

Scenario #2
Given I am not a Platinum user and I have purchased a new wheel, when I wish to return the wheel within 30 days of purchase, then I can do so without 75% penally.

Scenario #3
Given I am a Platinum user and I have purchased a new wheel, when I wish to return the wheel after 30 days of purchase, then I can do so with a 75% penally.

Scenario #4
Given that I am a customer who has returned a wheel, when I am given a refund, then I get a notification email.


User Story: Order an out of stock item 
As a customer I want to be informed on the status of out-of-stock items so that I can cancel the order if it takes too long.

Scenario #1
Given that I have ordered an out of stock item, and I have been told the wheel's delivery is 2 weeks, when the wheel is not in stock on despatch day - 1, Then email me and apologise and offer to cancel the order.

etc....

So why bother
There is a lot more information in these Scenarios and the process of getting people together and talking about these is hugely productive. You do not need a highly paid analyst or a developer guru for this stuff. You just need to start thinking, talking and recording. If it's incomplete and your project environment is evolving, then just starting is a great step forward.

Advice
What you can do, is pick a fictitious project, a small project, and go through the motions. This will be quite instructive.

Testing
In an earlier post I mentioned the INVEST acronym which stands for Independent, Negotiable, Valuable, Estimable, Sized, and Testable. This technique of writing Scenarios enables Testing and it go somewhere to assist Estimating.

I think the next post should be about using these User Stories and estimating work. I might wait for a week or so.

How to do User Stories - easy and fast but effective

Intro type waffle

I think that there are tons of people, developers especially, working in less structured teams, under pressure to get things done ASAP, wishing that they had more experience perhaps, and not really feeling that the project is totally in control or that they are not really getting the whole picture. This text is a quick heads-up on how we can quickly switch to User Stories to help us. User stories are a key concept in SCRUM so it might be worth thinking about getting your company to look at SCRUM. It is very good, it is simple, but it can be deceptively difficult for companies to adopt. But, even without SCRUM User Stories are very helpful in their own right.

1. We need to stop.
2. Lookup.
3. Look around us.
4. Ask some simple questions.
5. Then ask some more questions.
6. You now have some ideas - share them.

Writing stuff down is Good

The pressure to code first, to evolve the ideas on the fly, is big. Just because you do this does not mean you are being Agile. If it's a bit chaotic, don't convince yourself you are doing bits of SCRUM or XP when you're not. Don't give it a name if it doesn't deserve it. Rather, give your work a bit of structure.

Think before you code.

List all the types of people going to use the system

This is very important. It is usually quite quick, it often gives you a slightly different view or appreciation of the project ahead.

Don't really know the answer to this? Excellent. Start talking to the Client or Client representative and any major stakeholder (don't forget the department that might be supporting the completed).

If the Client / Business has names for these users already, then use those names. Don't create your own. Use the Business terminology if you can.

Don't keep this information to yourself. Share it. Even if it's in an email. If you don't have a BA, then make sure people up the management chain understand. Share it with other developers verbally.

Actively avoid using "User" as a role. Should it be, Premium user, Bronze user, Auditor, HR staff,...

The Secret is talking 

Talking, chatting, discussion - this shows that things are going well. There should be constant chatter about requirements and needs. Talking is a function of a successful project.

Core is Key
It really is. Whenever we talk about requirement, the functionality we want, the things the client needs. Keep one eye on it Context. Oh dear, I've mentioned Context without clearing up the meaning of Core. Always consider if the function is Vital to the business. Maybe you want to remember the MoSCoW mnemonic too, if that helps. But discover more about the domain, more about the business, and then discover if the feature is Core to the Business. Knowing this helps prioritise and makes sense of it in context. Context - well that can be any grouping of features or subset of the system or business. Any logical group that helps decompose the big problem.

Requirements - Stories are NOT contracts

Your junior colleagues, the management, the Clients - they will all think that once a requirement is written down it is finished with. They think you will go away and create something and you will return with a working thing. Emphasis to them that this is not the case.

Requirements will always fall short. They will always change or evolve.

The clients must not be scared of this. Embrace discovery.

Use the Business language

Ubiquitous language. Ensure that the developers and the Client Business use the same language. Use the Business terminology in preference to any technical jargon. Sometimes two departments in an enterprise may have slightly different terms for the same thing. Sometimes they are using the wrong term completely. Be aware of this. If you need to create a new term for a category or something, do so WITH the User or domain expert's knowledge.

List the Stories

Get writing the stories. This is quick to start and it will grow. Don't worry about getting it right or wrong, at least you are doing something. Stories are written from the perspective of the USER.

Follow this simple structure:

As a <put user role here> I want <put the feature here> 

so that <put the benefit here>

Divide and conquer the list.

Just start listing these down and keep them short and sweet.

To help get started, in your mind before you write the list, make some sub-headings on how you can break the list into related sections. Do whatever you want and don't think too deeply about it. 

Just get the list down. It will evolve and therefore whatever you write now will be either wrong or incomplete. Don't worry about that, it is good.

The list will not be complete.

Don't think you're going to capture everything if you're pushed for time. Instead, 

1. Start by listing the easy and obvious User Stories
2. Stop and think a bit, imagine the system is in use, and imagine who is using it, and note down the use cases that are difficult, risky, or likely to be forgotten by an under pressure developer.
3. Add some more.

Scope of the thinking

You start with an overview of the future and work down towards the detail. If you are a developer then technology will keep leaping into your mind and you can not avoid trying to implement the system in your imagination. This is natural, but keep it under control. Developers often focus on the technical detail and work up to the daylight of the overview. Don't do this. Imagine you are the Users of the system. 

You can break the scope of the project or the list of the Stories, into areas. Get a happy understanding of any areas that you would like to park and think about another day. 

So there we are. Job done.

Not quite but the work done to get this far is probably the most valuable in the project. 

Make sure you are talking to the people in the know and make sure you share your thoughts with others.

Discuss or think about the stories

They probably hide a lot of information about the system. If a story raises more questions than it answers, then you've hit a rich seam of value. You can break this Story down further and document it, or if you're  happy that the information is not needed on paper and has been captured, then don't. I would suggest writing it if poss. It is rarely wasted time.

At the end I'll give an example of breaking down a User Story and the types of question raised by an initial Story.

Where from here

These stories can now be taken forward and used in project estimation, planning and testing.
(That will be in another blog posting.)

But:

• We have improved our knowledge of the business.
• We have greatly improved our chances of success.
• We have disovered information about the system.
• We have a feeling for the risky areas of the development project.
• People are talking.

Summary

1. Writing is GOOD
2. Start asking question and continue asking questions.
3. List the Roles of the users.
4. Divide and conquer the list before you make the list.
5. As a <put user role here> I want <put the feature here> so that <put the benefit here>
6. Concentrate on Stories that are risky, likely to be forgotten, difficult.
7. Use the Client's terminology.
8. Discuss and discover more hidden in the stories.

Example:

A very common user story:
As a user I want get an order notification so that I know my order has been placed.

This is ok as far as it goes and is much better than nothing.

However, thinking about it a bit could raise some questions, such as:

Do staff members, the support staff get to order stuff?

Do the staff members need to create another account?

Can all Customers order everything?

Do we have a category of Customer, say Corporate, or Business, that can access certain areas? 

The answer to this is yes or no or maybe, BUT this question is not relevant to the User Story. It may well though generate another User Story along side of this. Or it might make us alter the list of Roles.

Email? 

Postal? 

Encrypted?

What happens if email is rejected?

How to ensure the email is correct before ordering?

Another email?

There's tons of things to think about.... and it's great fun. The problem is:

1. How do I record all this new information because I'm lazy and/or busy.
2. How do I make sure this information is used and acted upon.

Well the answer to #1 is related to #2. I would record it as easily and as quickly as you can and then share it as best as you can. If there is little project control for your project then assert some control around this area. If there is good project control, a Project Manger or team lead, then share with them. If you are the de facto team lead, even of a team of one, then do as you see fit. Communication is KEY.