If you are currently using or have used Agile processes in the past, you are probably familiar with the concept of framing project requirements as Stories and using those stories to complete the project. For those not familiar, a Story is a way to define an element of a project’s requirements from the perspective of the end user in a way that encourages discussion between the relevant members of the team. Here is an example of a user Story; you can see a goal clearly defined:
This method is very effective at capturing and putting emphasis on the value that a specific feature will have for the end user and why it is important to include in the project. Stories are intended to focus on the “why” and not the “what”, letting those involved focus on the motives behind the feature instead of how they should be implemented. Because they are meant to be “reminders to have a conversation” and not specifications or models, when it comes time to actually developing software to meet the Story’s guidelines, the Story itself has little guidance on how to implement a solution.
A Story is much too vague to use as a complete reference for development. Since it is meant to be a short summary of a particular need, it lacks many critical details that may be important parts of the overall requirements. When a developer reads a Story and implements a solution, they may implement many features that were discussed in the conversation about the story but forget about a key piece. Similarly with a tester, they may have not heard about a specific piece of functionality or nuance so necessary features may slip by incorrectly. The ambiguity of Stories also leaves room for assumptions; even after thorough discussion about the stories there may still be very different ideas about the details. This is especially prevalent in larger projects where Stories can encompass much larger features and is a real issue to producing a product that meets everyone’s expectations. To capture all of the finer details, something more than just Stories are needed.
For a productive development process, the developer needs the requirements outlined clearly, correctly, and concisely. This isn’t to say that we need very detailed requirements from the Client up front (that is actually something we want to avoid with Agile methodology), but after having discussions about the Stories then individual units of functionality should be captured. One way to do this is to capture details in the form of Acceptance Tests. These can help tremendously in making sure that the end result of the development process is exactly what the Client ultimately needs. Testers will have individual units of functionality that they can test against and these acceptance tests can even be converted into integration tests for automated and comprehensive testing. Developers can write code specifically geared towards satisfying those test cases and changes in the code that would normally pass syntax validation (but break desired functionality) are caught early. Continuing our example, here’s our original Story with some Acceptance Tests. You can see some important details that were captured:
However, even acceptance tests may not be enough information for developers to go off of (especially for front-end work) and it might be necessary to create additional documents, or artifacts, that explain the specifics of required functionality. These could vary based on the actual requirements you’re trying to capture; for example, a complicated process may be better defined with a flowchart than a verbose document, a mockup of a web page could more clearly explain some functionality than a flowchart, or a technical document may clearly define something better than anything else. It really depends on the functionality you’re trying to capture but the most important thing is to accurately convey it as succinctly as possible. Agile is lean in requirements, so the idea for any agile documentation is to model as little as possible while still containing enough detail to fully convey what is needed. The goal is the most effective use of time, and this process is called “Just Barely Good Enough”. Our example from before can be easily modelled as a mockup, giving developers a much clearer picture of the end goal:
With acceptance tests and artifacts (when necessary), the entire team will have a much more unified idea of what a Story truly means, and will all be on the same page from start to finish. This eliminates many of the problems that can occur with the non-programming side of software development. By getting exactly what is needed in the first iteration you will save time, money, and headaches by not having to deal with the back and forth between clients, testers, and developers.
This article was written by Josh Glass, a Business Analyst at Software Allies.