Companies that make the switch from Waterfall methodologies to Agile struggle with requirements documentation. How much documentation do we need? What kind? When should this documentation be created? Who is creating this documentation?
Our experience shows that companies have swung the pendulum too far in terms of both the quantity and quality of documentation when they make the switch to Agile from Waterfall. They are trying to get by with just User Stories and then using a hodge podge of emails and spreadsheets to fill in the blanks. Waterfall by its very nature forced very detailed documentation to be created at each step of the process – Envisioning, Planning, Development, Testing and eventually Deployment. In a Waterfall world, documentation is the means by which teams communicate with each other as the project moves from one gate to another. Continuous real time communications between the different constituencies – sponsors, business experts, analysts, developers and testers simply does not exist. This gap in communication is filled with exhaustive, detailed documentation.
In theory, in an Agile world, the real time communications that are taking place between the different constituencies in a project should fill in the blanks that are created by the User Stories. In reality, this is not how it works, especially in large distributed enterprises where the different constituents are separated geographically and by multiple time zones. It is not uncommon to have Agile project teams where the sponsors are in USA, key users in Latin America or Europe, analysts in multiple locations and the technical team is in India. Real time communications between these teams is neither practical nor sustainable on an ongoing basis. So we are left with huge gaps in terms of communicating what needs to be built based on a set of User Stories created by the users and provided to the development teams.
User Stories are a promise to have a conversation about what needs to be built. They are not the conversation in and of themselves. Herein lies the fundamental problem we are seeing with teams that are transitioning to Agile from Waterfall. The reams and reams of documentation of the past have been replaced with a product backlog with a bunch of User Stories and not much else. It is simply not possible to build any software, let alone enterprise software this way.
We understand that the goal of any Agile effort is not great documentation but working software. We are not advocating creating documentation at the same levels of detail as used to be done when using Waterfall methodologies. That is not practical in an Agile world and in many ways defeats the purpose of switching methodologies. Agile is not Waterfall delivered in small bite sized chunks. What we are advocating is using Models smartly to fill in the blanks created by User Stories as an effective means of communication within the team.
The reason for this is simple. Models do not derive their importance due to any specific development methodology. Models are used to articulate specific portions or aspects of the system. For example, Process Flows are the best way to communicate a sequential step of events that take place in a predefined and predictable manner. Business Data Diagrams are the best way to describe the different data objects that a business user cares about and show the relationship among them. Decision Trees or Decision Tables are the best way to show complex decision logic embedded in a process flow or event. And so on.
So, if a User Story relates to a specific process being performed or a portion of a process, the easiest way to model it and communicate it to team members is with a Process Flow. A story that talks to the movement of data across an interface is best modeled with a System Interface Table. Simply put, a team should use whatever model or models are necessary to articulate and flesh out the functionality that should be built to support a story or set of stories. This has nothing to do with whether the development methodology is Agile, Waterfall, some combination of the two or something else altogether.
Nothing cuts across time zones, geographies, languages and other practical barriers that prevent all the members working on an Agile project from being co-located like Requirements Models. The specific models to use will be dictated by the realities of your project and what you are building. I wish I could lay out a neat little list of models to use in Agile project to the exclusion of all else. It does not exist. Never did. Never will.
Once the Models are built, the Acceptance Criteria for your user stories practically write themselves. Some models like Decision Trees and State Tables can be used as proxies for Acceptance Criteria in their own right. Models do not lose any of their utility because the development methodology has changed. If anything they show their inherent value by proving their utility even as the way in which software is built changes profoundly by switching to Agile from Waterfall.
Use Agile principles when it comes to answering the second order questions around documentation. When should I build the Models? In time for the development team to consume them, not earlier than that. Who should build them? Your Analyst or anyone who can build them. How much detail goes into the Models? As much as is needed for your users, developers and testers to agree on what is being built.
ArgonDigital makes available templates for over 25 different models that address different aspects of a system. You can download them for free at the link below. I am certain you will find these useful and your projects will be better off for using them. Good luck with your efforts.
https://seilevel.com/business-analyst-resources/business-requirements-models-templates/
