Documentation in Scrum part 2 — the business rules
Their importance and when documenting them
Previously, I published an article in Mastering Agility, “Let’s talk about Documentation in Scrum”. The article discusses the importance of documentation in Scrum teams and which kind of documentation should they produce.
In short, at a minimum, a Scrum team must document the artifacts from the Scrum Guide, namely:
- The Product Backlog, together with the Product Goal
- The Sprint Backlog, together with the Sprint Goal
- The Increment, together with the Definition of Done
There were other complementary practices that, although not part of the Scrum Guide, might be useful to bring the team’s work in the right direction. In the article, I suggested documentation such as:
- Vision statement
- Product roadmap
- Details of a Product Backlog Item (PBI), together with its acceptance criteria
- Scenarios (e.g., in Gherkin format)
- Supporting models
In this article, we discuss another optional documentation, but a personal favorite (and which I would wish to have perceived its importance): the business rules!
In this document, the purpose is to identify, express, validate, refine, and organize the rules that shape day-to-day business behavior and guide operational business decision-making. (Source: definition of business rules analysis by the International Institute of Business Analysis, IIBA)
Requirements are used to implement business rules. Hence, the requirements of a feature must ensure compliance with the business rules. Therefore, if a business rule changes, your business requirements will be impacted and need to change also. More practically speaking, rules are business requirements, though not all requirements are business rules.
Why should we document the business rules?
Why should we write yet another document? Why do we need to gather all the business rules? Below are a few examples, there could be more for sure:
- have the rules in one place. My experience tells me that rules tend to be discussed, yet remain undocumented. Rules like the specificity of a business process, a given policy, or a legal issue, among others. Sometimes implicit, others explicit, they were part of a requirement. But, as the development goes on, it’s easy to lose track. A dedicated document that joins all rules from the beginning makes it easier to find whenever you need to consult or revisit a rule, right?
- we can use it as a query in tests. When planning all test cases for a feature, the test scope for the main flows and all alternative flows will go around such business rules. Also when planning for conducting UATs, having the document helps define the tests to be made.
- as a customer support query. When we are in customer-facing tasks, we are often asked to verify if a given solution is behaving properly, even if that is not clear to the customer or end-user. For proper answers, we should back up our answers after consulting the business rules and verifying if the situation that the customer is asking about is properly following the business rules or not.
- as a decision to classify it as a bug or not. How often do we verify a given delivery and when something seems weird, you decide to report it as a bug, only to reverse it after long discussions? Some deliveries must comply with complicated regulations or formulas, and when you have to double-check if they are properly applied or not, a document with a structured rule eases such work.
When should we fit this documentation within the delivery process?
We can discuss how the work related to the document, as it may be managed in the delivery process in two ways. Even though most of the documentation tips are exemplified throughout the article within Scrum, they can be used in any other way of working.
The first way, and perhaps the ideal one, is if the business rules documentation starts at the beginning of development. I believe it’s ideal because that way it’s a practice done since the very beginning, hence easier to document them iteratively as we need them.
Another way is to document the business rules in the requirements within the acceptance criteria, rather than a dedicated document. It’s normal to document the rules within the acceptance criteria. But also it should be kept in mind, as discussed above, the advantage of having them in a single place.
Unless all acceptance criteria are easy to find, I would suggest reusing the same text of the acceptance criteria for a business rule in a document that gathers all the rules. It may become tricky because you need to have a single source of truth for your project or product, so maintaining two separate sources and ensuring they are all updated and matching each other is hard. One way to make it a bit easier is to use tools of online and living documents, where you can have pointers between one another or add in one place after you create something new on the other.
In the case of this approach, if the business rule is transversal to the solution, instead of using them in the acceptance criteria, they can be included as part of the “Definition of Done” (DoD).
What about if a rule was already delivered?
Until now, I’ve described how to document business rules as they are addressed during the delivery of a feature. However, if there are already some features that have been delivered but those rules are not documented yet, that doesn’t mean you can’t start your business rules document. It will demand you to invest some time to re-visit a thing from the past. But I am sure this investment will come in handy in the future.
In this case, my suggestion is to include in the work planning a dedicated time slot where the document can be constructed incrementally. Alternatively, for example, when we come across a business rule in a UAT or customer support, it is a good time to add the rule to the document.
How to document?
After discussing the when, it’s time to talk about the how.
You can work on a document following a typical structure for it. It may be the case that this kind of document keeps being associated with a “traditional” (before agile, waterfall-like) way of working.
An interesting location to store the business rules is at the epic level. By following a documentation format proposed by the “Epic alignment” from Nils Janse’s book of the same name, business rules stay in the form of a living document and are easy to find and add more.
In this approach, the document is suggested to be written in a tool that enables live documents and easy outliners, such as Google Docs. The epic level is the chosen level for the scope of the document. Each epic is described with its user stories and includes all relevant information gathered from discovery to the delivery stage.
My suggestion here is to have a dedicated section about the business rules applied to a given epic. Using the epic level helps you searching a rule by a theme or topic, rather than searching for a business rule within all your Product Backlog Items (PBI) or user stories. The use of an online and living document enables the use of pointers and links, so you don’t have to add new business rules and maintain them in separate sources (for example, within a PBI and a business rule document).
An example case
Let’s say that you are developing a Feature for the accounting data of your clients. You have a set of PBIs under the same epic. Let's call the epic “Clients accounting sheets”.
You have a PBI1 that is about the client’s tax identification number. For that one, if the client is from France the identification has 9 digits, but if they are from Cyprus it has 9 characters and the last character must always be a letter. Business rules will have at least these 2 digits rules.
The PBI will have an acceptance criteria of a “valid identification number format according to its country” and you may complement this AC with gherkin statements (“Given…When…Then…”) regarding these 2 cases.
When writing your test cases, you will plan (at least) these 2 tests for validating the PBI. If a user complains about an error message in this field, you can consult these rules to check if it’s the user to fill them incorrectly, or, if on the other hand, it’s the software that’s not performing right.
For a PBI2 you have a postal code from the client’s address. Again, the format of a “valid postal code format” depends on the country. It will have similar acceptance criteria as the identification feature, as well as the test cases.
Your Epic document with all the PBIs, acceptance criteria, test cases (and all the other topics as suggested in “Epic alignment” above, but for this example, they are hidden), and, in the end, a list of all business rules gathered for this epic, would look something similar to the image below. Look that, in the acceptance criteria, there is a pointer to the Business Rules section.
Clicking on the pointer, you are forwarded directly to the business rule.
When you want to consult all the business rules from the client’s sheets, you know they relate to the epic “client’s accounting sheets”, so you open the epic living document and it has links to all business rules within acceptance criteria from PBIs that belong to this epic.
The outliner that is on the left side makes it very easy to quickly find the business rule and the context they come from (PBI, acceptance criteria, etc.) and also to add new entries for this epic.
Key takeaways
- Having a business rule documented helps have explicit your project or product compliance needs;
- They guide teams in the delivery, testing, and maintenance of features;
- It’s not hard to include them in the delivery, as they are usually part of the acceptance criteria of a feature;
- If they weren’t documented yet for features already delivered, you should consider investing some time in re-visiting the past ;
- Online and living documentation tools enable you to have them as a single source of truth.
