Agile development methods focus on defining "just enough" requirements detail for the next sprint. In other words, don't produce any requirements specifications that are not absolutely critical to getting the point across to the rest of the team. So how do you decide what is "just enough," and who makes this decision? What happens when the team is co-located or distributed? How do you deal with changes to these requirements details and their priorities? Let's take a look at the answers to those questions and others.
How do you decide what is "just enough"?
Deciding what is "just enough" is simple yet complex. Simple in the sense that you will know when you get it right and complex in the sense that there are many factors, such as team size, proximity of team members, complexity of the software being built, whether this is an "add on" feature or an entirely new system or product, and competing business pressures of breadth of features vs. quality of features. In the end you likely want to identify some guidelines for how you want to define requirements for your team. This article provides a starting point for such guidelines.
Choosing the level of detail
One of the first things you will want to decide upon is how much detail to include in your requirements artifacts. The table below provides some thoughts on how to go about making your decision, but in the end be prepared to change your course during the sprints.
When "story cards" are not enough
A popular and valuable technique within Agile development teams is to create a story card. These story cards tend to provide a text-based description of who wants to do what and why, along with perhaps a picture of the screen and some test scenarios. This technique works well for very small features, but it may not scale well for larger or more complex features that integrate and depend on other features.
Don't force the wrong technique
There are a number of well-proven techniques for capturing requirements. Choosing the right one at the right time is the trick. For example sometimes just a simple little text description outlining who, what and why, like those found on a story card is enough. Other times, adding to that description a simple picture, perhaps of a screen mockup with annotations is more appropriate.
Sometimes to truly understand the overall flow of a more complex requirement "use case flows" and/or "simulations" are required to capture "just enough" requirements. However, from my point of view, it typically is not a good idea to use "use cases" to document complex logic or business rules such as authorization logic. These types of requirements are often better documented in text or tabular formats. For example a simple 2x2 table showing the roles on one axis and what they can do on the other axis is a much more efficient way to convey authorization business rules than embedding alternate flows into use cases.
Also, when doing simulations it is possible to spend too much time doing elaborate simulations that don't add enough value for the effort they can take to develop. Simulations can add great value to really bring a concept to life, but adding every single detail into the simulation can take too much time, and frankly it is sometimes difficult for developers to reverse engineer a simulation and extract a discrete set of requirements. Using the authorization business rules again, it is much easier for a team member to read a simple 2x2 table that shows who can do what than it is to run through a simulation and reverse engineer the same information.
Everyone will have their personal preference as to when to use what technique for communicating requirements, but the key is for the team to work together and agree upon when it makes sense to use different techniques and not "force" a technique when it clearly can be done more easily another way.
When verbal is better than written
Verbal communications with perhaps a whiteboard session are typically the fastest way to convey a requirement. But what that approach makes up for in "initial" speed, it lacks in ensuring all stakeholders are in the loop and sometimes leads to too many assumptions about details. It is all too easy for people to have different recollections of details discussed two weeks ago let alone two months ago. This can lead to misunderstanding of requirements during development, testing, writing product user guides and training material, all of which wastes time. So you may have saved time initially, but you wasted more time in the long run.
So when is verbal better than written communication. Agile methods suggest that communication over documentation is better, but in my experience this can be taken too far and cause too many issues downstream. Relying only on verbal communications is a last resort when short-term time gains are worth the longer-term issues this approach can create.
Capturing meeting minutes or taking photos of whiteboards is a starting point for communicating all stakeholders' issue. However, if photos and minutes are lost in a sea of email and not in a central repository linked to other related requirement details, then the team will find it difficult to keep track of the web of requirement details.
Keep everything linked in a central repository
No matter what techniques you decide to use to document requirements, keeping these requirements details/artifacts in a central repository and linking them to each other in an organized manner is critical to the collective success of your Agile team. You cannot rely on people to keep track of endless email trails and simple document repositories with manually maintained links. People are too busy to maintain and update links requirements artifacts manually, which in most cases will lead to them not being kept up to date. That means that whenever possible the repository needs to automatically create and maintain these links based on how you organize the artifacts. For example if a use case refers to a screen on a given step, that screen should be automatically linked to that step in the repository.
This topic is much deeper than can be covered with this small article, but the key points to take away are as follows:
- Make a conscious decision on the level of detail you want to start with, but expect to tweak that during the sprints.
- Choose the right technique for the requirement you are trying to describe.
- Make sure you keep an integrated central repository that links together the inevitable multiple requirements artifacts.