How Agile Requirements and Project Documentation Live Together

Just In Time and Fit for Purpose

Agile developers work under the assumption that uncertainty is so common and change so large that no upfront architecture and design can possibly be exactly right or fit for purpose further down the line. Therefore, development is iterative and as simple as possible, with a refactoring approach to architecture and design.

Agile development teams start with an idea, break it down into features and functions, write high-level requirements and then get started. The objectives are to document just enough to proceed with construction, complete a select set of the highest-priority requirements in each sprint, collect requirements in a backlog and produce documentation that anyone can use when they are working with the software.

Having documents that anyone can use is a laudable goal; however, in some cases, a document that is supposed to be fit for everyone ends up being fit for no one.

The Maintenance Documentation Gap

Many business-critical projects, such as commerce applications or portals, are now agile. In these projects, it’s common to have an outside agile development shop creating the application. The shop works on the project for 12–18 months and then it is turned over, either to the company that needs the application or another vendor, for maintenance.

Although the lightweight stories and requirement artifacts work really well for construction, they can’t just be handed to maintenance as is. These stories and artifacts do not have the information needed to maintain the application for a number of reasons.

Often, when a team gets in the middle of a big project, things change and those changes might not make it back into the documents. The attitude is that the software has already been delivered, and it’s time to move on to the next sprint. So, maintenance ends up with out-of-date documentation. In addition, agile documents are often very minimalist without the overview often needed by a maintenance team.

The Audit Documentation Gap

In some industries, there are often outside rules and regulations that applications must comply with. Because traceability is important in large projects, large agile teams often use tools to link artifacts for traceability, but at times, these are not sufficient.

For example, I worked on a big portal implementation for a pharmaceutical company. It was an internal portal that involved data from drug studies. In that situation, not only was the data access subject to audit, but also the construction of the data access portal itself. Although we linked artifacts, we were very focused on developing the application and website, and there was a scramble for documents and required traceability when the auditors showed up.

Like maintenance documentation, the information auditor’s need is not necessarily found in “one-size-fits-all” requirements documentation. Attaching traceability to the project is also not sufficient. Auditors need documentation that demonstrates compliance.

Agile Documentation

Closing the gap between the documentation produced for agile projects and the needs of maintenance teams and auditors can be achieved by taking the same approach to delivering documentation as that taken for delivering code. Instead of producing documentation that everyone should be able to use but can’t, think about providing maintenance and audit documentation as separate deliverables.

In the projects I work on, we decouple requirements, stories and artifacts and create other deliverables that are part of the sprints. For maintenance, we build some frameworks based on what maintenance wants. We harvest things out of agile requirements and then look at what gaps exist. Part of the sprint is filling in the gaps.

For audit documentation, we get the full requirements and make them part of the story. In fact, the story is not complete until we have run the report and compliance matrices and connected them to the story. We recognize that we might have to add more traceability, that compliance and audit regulations are continually evolving and emerging, and that we need to keep up.

Coexistence

Requirements, artifacts, maintenance documentation and audit documents can all coexist, not necessarily in the same location, but as part of different sprints. And when you take the just-in-time and fit-for-purpose approaches, all of which include taking advantage of reusable parts when possible, generating documentation is easier.

After all, when you look at maintenance manuals or administration guides, you can see that they contain some elements found in design documents. Some of the traceability required by auditors is similar to what agile project teams want, such as links between business need, development work item and acceptance tests.

In the agile projects I work on, we identify these similarities, publishing out a shell and building a template with an outline that includes an extract from the business process flow or architectural diagram. Some of the objects we create in other tools can be inserted in the manual. The result of this approach is “mini-ocuments.” Our mini-documents for maintenance have been more popular than even the older large design documents because maintenance teams can move right to the space where a defect is detected. They no longer have to deal with huge documents that are difficult to navigate.

Conclusion

Documentation for applications built by agile development teams that are based on requirements, artifacts and stories can come up short when they are needed for other purposes such as maintenance or audits. Providing documentation that suits different purposes is possible if you take an agile approach. Determine documentation needs upfront and include the different documentation builds in your sprints and you will provide the right documentation solution for all stakeholders, including maintenance and audits.

Don’t forget to leave your comments below!

---

Kurt Solarte is a Managing Consultant working for IBM Australia in Sydney; focusing on Agile Development methods. Kurt recently spent eight years with IBM Global Business Services in the U.Ss as a Sr. Business Analyst; where he specialized in keeping business analysis alive and relevant in the agile delivery of eCommerce, web portal, and business analytics projects.