Most of the projects that we work on here at ArgonDigital involve producing some sort of coherent documentation to describe what a given piece of software needs to be able to do and how it will work. Of course, software requirements are a crucial part of this documentation, but by themselves they aren’t enough. For your documents to be fully effective, they need to be able to tell a story.
Every story has a beginning, a middle, and an end. The beginning is where the storyteller sets the story’s context, introduces us to the characters, and lays out the problem or challenge that will drive the rest of the story. The middle is when most of the action takes place. The end—at least in stories with happy endings—is where the problem is resolved, the characters go home, and everyone is happy. As business analysts, we should strive to provide a similar narrative to our documentation.
The Beginning
The beginnings of most stories set the time and location that the story is taking place. For example, when we sit down to watch Star Wars, we are told in the opening 5 seconds that the movie what we are about to watch takes place “a long time ago in a galaxy far, far away.” It’s pretty obvious, but this information is really important for helping the reader understand what’s going on, make sense of the rest of the details in the story, and frame the actions of the different characters so that the reader can make sense of what’s going on. The fact that Star Wars is taking place in a faraway galaxy helps to explain why robots can talk, characters can travel between planets, and (spoiler alert!) Luke and Darth Vader can fight each other with laser beams!
The beginning of our BRDs and SRSs should lay out the context for the story. Here at ArgonDigital, we use a few different models to do this. First, we use a Business Objectives Model (BOM) to provide the high-level business problems that our software project is aiming to solve. If the BRD is only describing a portion of the overall project, the BOM can be used to show where our bit resides in relation to the rest of the project: what part of the project does this document describe? What problem will be solved in the rest of the document? The introductions to most stories give the reader insight into the motivations of characters that helps to explain their actions later on in the story. Providing a similar type of context at the beginning of a requirements document will allow users to place the rest of the information they will encounter in the document into a coherent framework.
If the BOM explains the “what” of the story, the Ecosystem Map provides the “where”. The Ecosystem Map shows the different systems that are involved in a given project. The purpose of the Ecosystem Map is to define the scope of the project, show how systems are connected, and to show what information passes between systems. Later on, when we get in to the different requirements for each system, the reader will be able to understand each requirement better from the information displayed in the Ecosystem Map. Much as an author will provide the setting and context where a story takes place at the beginning, we as business analysts can do this with an Ecosystem Map.
In my next post I’ll talk about the importance of the Middle and the End of the narrative, and how we tell those parts of the story here at ArgonDigital. Stay tuned, and in the meantime: do you do this on any of your projects? Or think about requirements documentation this way?
[hr][/hr]
