Lately I’ve been working with a customer who is making the transition from waterfall to Agile project delivery. Among the many challenges the organization is working to overcome, their project documentation templates and practices were very much oriented to a waterfall world. Each project would require a requirements document that was generally over 70 pages long, and project stakeholders were required to review, understand, and approve this massive document so that technical design could commence. Once the documents were approved, it took considerable effort for the project team to convert the requirements into the format required for the customer’s Agile backlog management tool.
For the second phase of the project, we decided to try a different approach to documentation. So we created an Agile Requirements Document (ARD). We structured it to mimic the structure of our Agile backlog and peeled off all of the seldom-used-and-never-read sections of the old document. We added an introductory section just to explain the Agile process and the use of our document within that process for people who aren’t familiar with the concepts. We wanted to make sure that the business team understood that their engagement was necessary throughout the entire software development process, and that the ARD was the beginning, not the end, of that road.
We also changed the ‘document approval’ section. We still have a list of approvers and reviewers for the document, but clarify what approval means in the Agile world, as follows:
The section tracks the review and approval of this Agile Requirements Document. The Approvers agree that the following document adequately reflects the business needs and that the documented user stories should be included in the product backlog. These represent the knowledge that we have at this time and are subject to change as we learn more during the Agile product lifecycle.
The sections of our new document are theme, feature sets (also called epics), features, and user stories. At the theme level, it might be appropriate to include a Business Objectives Model, an Ecosystem Map, or a Business Data Diagram. At the feature set level, I use a Feature Tree. Each L1 branch of the Feature Tree is one of the feature sets. At the feature level, Process Flows are the best model to use, although a Data Flow Diagram or Decision Tree could also be useful here, depending on your needs.
Our plan is to create a separate ARD for each theme. Depending on the complexity of the theme, the document will average between 10-25 pages. We could include multiple themes on one document, but by keeping each document small we achieve two things. One, they’re much easier for the business users to read and understand. Two, having a narrow focus actually helps the business analyst create higher quality documentation. When I created the first draft on the theme of warranty extensions, I discovered that I was actually having fun writing a small, polished gem of document instead of the usual, 100+ page monstrosities I’ve written for this customer in the past.
While it would be possible to create all of the information contained in the ARD directly into the backlog management tool, we decided against that for a couple of key reasons. One, the tool is not accessible to all of the business users, and two, the ARD is a much easier format for the review and approval process.
Our customer is not finding the road from waterfall to Agile to be an easy path, but it’s good to remember that small changes can make a big difference. A simple thing like realigning a document to an Agile point of view can help.
