Skip to main content

Author: Amanda Bennett

How to Fill the Potholes in your Business Requirements

It is springtime in Ottawa, Ontario, Canada. Beautiful, glorious, Spring! Everywhere you look, the signs are there: frozen rivers are starting to flow, birds are returning and filling the air with their sweet melodies, snowbanks are shrinking, and…oh yes, potholes are showing up everywhere in the roads. As much as I try to avoid them, somehow they always get me. It takes a special breed of car to survive the tough Canadian winters. My Honda Civic is on it’s 10th year, 161,000 clicks, and still going strong.

Trying to avoid the springtime potholes is a fair analogy to a task that I am often asked to do as a Senior Business Analyst: reviewing and providing constructive criticism on business requirements written by someone else. A road filled with potholes can wreck your car, just as a poorly written set of business requirements can wreck a project. My job when reviewing business requirements is to look out for these potholes, make the writer aware of them, and provide suggestions on how to fill them.

Digesting business requirements written by someone else can be challenging, depending on the writers experience, knowledge, and ability, so to make things somewhat easier, I provide a template for my clients to use. Before they start their requirements, I will meet with them to explain how to use the template and to discuss any questions they may have. Using a template, I at least know the intent of all the sections of the document, and it gives a greater consistency to the documentation I have to review.

Once the written requirements are sent to me for review, I start by analyzing the document from beginning to end. One of the first things I look for are acronyms or business terms that have not been defined. This usually happens because the writer thinks that they do not need to elaborate on the use of terms internal to their business unit, but they forget to consider the audience of the document they are writing. Clear and unambiguous definitions of business terms are especially important to the developer, as they can have a direct impact on how they architect the system.

I also pay a lot of attention to the process diagrams of the current and future states. It is a very common mistake to omit the alternative paths to a process. It is understandable how this can happen. People assume that because the process usually happens a certain way, that they do not need to mention the other rare scenarios. Others may think they only need to describe the perfect world scenario, and forget to think of all the what-ifs. For a manual (non-computerized) process, unusual scenarios can be dealt with simply by communicating with those affected. When the process goes electronic, it is another story. The programming logic has to include all the alternative paths, or the system could fail spectacularly. This is a mind-shift for people that can take some getting used to.

When I am ready to dig into the detailed requirements, there are a few things I am on the lookout for. First of all, what I do not want to see are long, wordy paragraphs with several requirements buried within it. It may feel more natural to write this way, but not only is it painful to read requirements this way, it also greatly increases the likelihood that a requirement will be missed somewhere along the way, either during the development, or in testing. A much safer practice is to write each individual requirement separately, and give it an identification number. That way, even if a requirement does get missed during development, it will get picked up in the testing, assuming your test scripts have appropriate requirements tracing as well! That’s the topic of another post.

Secondly, I want to see a clear link between the in-scope deliverables laid out in the project charter, and the detailed business requirements. This is so important, because people can and will forget (perhaps conveniently sometimes) the original goals of the project, and before you know it, the scope of the project has grown exponentially. Believe me when I say, this is a crazy train that you do not want to be a passenger on. To create that linkage, what I will do is ID each of the in-scope deliverables, and use them as the parent IDs for the detailed “child” requirements. That way you know where each requirement is coming from.

Finally, I watch out for requirements that delve too deeply into design details without properly explaining the need behind it. This is a risky thing to do because when describing design details as a part of requirements, you limit the technical architect’s (or whatever you call that role) ability to design the best system to meet the client’s needs. That said, there may be cases where a specific design may be warranted, but the reason for that should be explained clearly. There are, in fact, some people who feel that requirements should not contain any design details at all, and only state the need. Others feel that not only is it ok to include design in the requirements documentation, but fully expect it. This is a contentious issue that I will not attempt to resolve here, but suffice-to-say that you should do your homework before you start writing your requirements. Find out what the practice has been in past projects, and what is expected of you now.

While this is not an exhaustive list of everything I am on the lookout for when I review someone else’s business requirements, this represents the bulk of my work. Hopefully you’ve read something new in this post, or at least can relate to what I’ve written.

If you would like to weigh in on this topic, please leave your comments below.

A Real-World Example of the State Transition Diagram

Whenever a workflow of some kind is being converted to an electronic process, you’re going to be looking at creating a status-driven process. That’s because the object passing through the workflow needs to receive status changes to indicate that the previous step is completed, and to trigger the next step of the process. Recently I was involved in a project converting a thesis submission process from a paper-based process to an electronic process and it serves to illustrate the usefulness of the State Transition Diagram for this type of project.

In this example I used the Bizagi Process Modeler to create my State Transition Diagram. I prefer it over the other tools I use because it’s free, the diagrams are more aesthetically pleasing than the other tools I’ve used, and it is quick and easy to use.

Bennett Dec11 Img01To give you some background about the project that the State Transition Diagram presented below is based on, the submission of Master’s and Ph.D. theses in my institution is not overly complicated, but there are many different forms that must be completed by a variety of people, including students, administrative staff, and faculty. I needed an easier way of explaining all the steps of the process and what forms were being released at each step. Enter the State Transition Diagram.

Something else we had to make a decision on with this project was where to start the electronic process. The thesis submission process is lengthy, and we had to decide whether to include the part of the process – before it is officially deposited at the Graduate Studies office – when the thesis is still under development. To reduce the scope of the project, we decided to start the electronic process after the thesis has been developed and the student is ready to officially submit it to Graduate Studies.

Click image to view larger.
Bennett Dec11 Img02

This diagram demonstrates the status progression of the submitted thesis. Starting from the left, we see the first status is “Pre-Upload”. This is before the thesis is uploaded by the student. The circle following that status is the “Thesis Uploaded” event. Any circles like this one that have a double border around it are known as events. This first event indicates that the student has uploaded their thesis via the new electronic process. From this event we see a dotted line leading up to a gray rectangle, known as an annotation. The items listed in this rectangle indicate the forms that the student must complete as they upload their thesis. Once this event occurs, the status of the thesis becomes “Thesis Package Received”, which triggers the release of the Thesis Defence Authorization Forms. These are forms that go to the members of the defence committee who must decide whether the thesis is suitable to defend, hence the decision diamond that follows this status: “Defence Authorized?”. If the decision is no, the status of the thesis becomes “Defence Denied”. If yes, we next see the “Notice of Defence Approved” event. This is where a notice is posted in some locations around the university listing the members of the defence committee, and the date, time, and location of the defence. Once this event occurs, the status of the thesis becomes “Ready for Defence”, and from this status we see another annotation leading upwards listing some more forms that are released with this status change. Following this status is the “Defence” event. This is where the student defends their thesis before the defence committee. At the defence the committee will determine whether revisions are required or not, and thus we see another decision diamond for “Revisions?”. If the decision is no, the status proceeds to “Thesis Accepted”. If yes, the status becomes “Requires Major/Minor Revisions”, and in the annotation above this status we see the Thesis Revisions Approval Form is released. Following the “Requires Major/Minor Revisions” status is the “Revisions Uploaded” event. This is where the student has uploaded their modified thesis according to the revisions that were provided to the student at the defence. At this point the decision must be made as to whether to accept the revisions or not, and so we see the decision diamond “Accepted?”. If no, the flow goes back to the “Requires Major/Minor Revisions” status. If yes, it proceeds to the “Thesis Accepted” status. Going down from this status is another annotation showing the final forms that the student must complete before the thesis is electronically packaged and sent to the Library for publication. That’s why the next event we see is “Thesis is sent to the Library”, followed by the final status “Transferred to Library”. This is the end of the electronic thesis submission process.

Explaining this workflow to my stakeholders with the help of this State Transition Diagram that they could follow along with was much easier and was more meaningful than reading just a written explanation or explaining it verbally. It may not be a useful tool in all situations, but for workflows, I find it indispensable.

Don’t forget to leave your comments below.