In the beginning, there were requirements documents

February 4, 2015 Adam D'Angelo 0 Comment

DocumentationA previous project I worked on had nearly 1,000 pages of requirements documentation for a web-based system. This project was run using a typical Waterfall approach in which the requirements were gathered and a set of requirements documents were written, revised, and approved long before development began. Our team spent thousands of hours writing these documents that would eventually become the blueprint for the software we would implement. As typical developers, we were thrilled when the stakeholders signed off on the requirements documents we had spent the better part of a year writing. However, halfway through development, we started to come across major issues with the requirements. Certain items did not make sense, were not clear enough, or simply were not adequately defined to continue. We were knee deep in developing certain features but had to come to a full stop until we were able to get the answers we needed. Months passed as features were removed from the requirements and new ones were added. An overhaul of the system’s architecture began to adapt to these major shifts in priority and focus. Our team was frustrated with the changes, and it was devastating to the morale of the team to find out the hard work we had put in was essentially worthless.

An Agile approach to development using Scrum may have solved some of the major issues we encountered. With Agile, we don’t depend on fully fleshed out requirements for an entire system before beginning development. Instead, Scrum teams allow documentation to grow to its project needs and to continue to develop and change throughout the process. As a result, we still end up with a well-documented system, but that documentation is better tailored to the needs of the project, easier for stakeholders to review and understand, and easily modified throughout the process. Key elements of Agile requirements documentation can include the following.

  • User Stories: User stories or epics outline the features that will make up the software, but they leave out details that can bog down the requirements process. For example, we do not include detailed database design or complex class diagrams. Instead, we state the success criteria as the definition of done. This definition of success will let the developers and the product owner know that a story is complete when it meets the criteria, and that a feature has been successfully added to the software. There are many great resources out there for how to develop user stories, but a favorite of mine is User Stories Applied: For Agile Software Development by Mike Cohn. After the sprint, if a Scrum team demos the feature to the stakeholders and they find that the story was not exactly what they meant, it is easy to make changes and create a new user story to adjust the software’s functionality.
  • Wireframes: Visual requirements in the form of wireframes are very successful for giving the stakeholders an idea of what will be created. Often, non-technical stakeholders identify more with images and screen mock-ups than with a detailed requirements document. These images show not only what a screen looks like, but also what the user should expect when submitting data, navigating through the application, or how different application states can affect the user interface.
  • Wikis: One of the more successful replacements for a comprehensive design document that I’ve seen in action is a project wiki. The team is responsible for updating the wiki with any system architecture additions or changes. It’s easy to build in updating the wiki as part of the success criteria for a story to ensure developers add pertinent information. Between the wiki and self-documenting code it was easy for new team members to get up to speed with relative ease.

The documentation was not solely to blame for the problems we encountered on my example above, but had we allowed for the documentation to grow iteratively it would likely have uncovered other problems—like stakeholder disagreement—earlier. In Agile, we look for ways to create working software by using documentation as a tool to get us there, not so that documentation is the output itself.


This is the third post in a series where Adam D’Angelo–one of Dev Technology’s Project Managers and an experienced developer–shares his experience using Agile development over the years to continue the conversation on how we can use Agile to build better software. View the full series here.