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.