The idea behind “Agile” way of documenting is a significant change from the traditional documentation. In agile way of development and delivery, the emphasis is always on “Just Enough” documentation and “Just in Time” documentation.
The downside being, In the quest for rapid and shorter iterations and sprints, there is a chance that the Agile teams might produce little or no documentation at all!
As in all aspects of life, the key is to strike a balance. This might look like a cliché, on the contrary, if the teams are able to follow the following key steps, this is achievable.
1. Awareness – Awareness is a key ingredient for success. People (Business, Architecture, Design, Development, Testing, Support, Infrastructure) should be aware of each other’s requirements in terms of the information needed to perform their duties to the best of their abilities. This means that everyone accepts what is “too little” and what is “too much”.
2. Education – Since Agile is a new way of doing things, people involved must be educated, and sensitized to the new way of doing things.
3. Collaboration – A lot of review, rework, review cycle can be reduced by encouraging a collaborative environment and equip the team with appropriate tools to facilitate collaboration.
Some of the best practices I would recommend are as follows.
Document Late: Critical documents like Service Specification, Service Design are done much closer to the actual development of the services. This allows the services to be evolving and can accommodate changes at much later stages.
Targeted Documentation: The documents produced are focused on the consumers of the documents.
Communication & Collaboration: With the combination of Agile and Off shoring, we have to be much more flexible in terms of being communicating and collaboration. Use WebEx sessions, white boards, Instant Messaging, Telephone, and most important of all a WIKI as collaboration tools.
Automate where possible: I have seen majority of the content for Service Specification generated from WSDLs. WSDLs in themselves are nothing but a specification of the service interface.
Once a WIKI culture is firmly established, it becomes rich in content and an evolving information store. Generating documents like operation manuals from WIKI, can prove to be an effective way to provide information to the Support team.
The other automation ideas
Automatic Release Notes Generation – using the information from WIKI, and SVN to generate the Release notes.
Automated Review – of artifacts like WSDL, XSD, WIKI pages, against various compliance checks.
Service Dependency Documentation Dependencies between services and back ends are discovered and documented from WIKI, SVN and/or Enterprise Repository. No need to maintain a separate dependency matrix.
Requirements as tests: A single source for designers, developers and testers instead of requirements document, design traceability matrix, and test case document.
In Summary, A strong awareness, and clearly defined documentation requirements combined with a culture of collaboration, we can address the documentation concerns of stakeholders while following Agile delivery.
thesoaarchitect
A hands on SOA Architect's Blog 