So I have been wanting to write down this post for last several days, and I finally got to it tonight. So here it is….
By now, I have lost count of how many times I have heard people saying that when using Agile methodology, we do not need any documentation. I think it is important to go back and read the Agile manifesto, where it clearly states that we value “working software over comprehensive documentation“. No where in the manifesto, it is stated that we do not value or need any documentation at all.
Yes, I agree that the era of creating stacks-n-stacks of requirement documentation, before getting into the development cycle, is gone; but we cannot eliminate the need of certain key documents that in my opinion, tie the entire software development project together – from inception to delivery, no matter what flavor of Agile you use.
I urge my teams to use the following 6 documents for any project we work on. None of these are heavy documents. Infact, some of them are just a 1 page document.
- Business Process Flow: This is something a Product Owner can put together. The idea of this document is to have a one page process flow that explains the business need and the solution the software would serve. This document can highlight the various business components and users that would interact within and around the system. This can serve a great tool to educate the team before diving into the project.
- User stories and acceptance criteria: No matter what tool you use – Jira, TFS, Rally etc, soon enough all your work items features, user stories etc get scattered into the system. Having a running document that lists all your user stories and their acceptance criteria comes in handy, when tracking the overall work progress of the project. Reading through a running document helps focus your train of thoughts, rather than trying to browse through a series of scattered user stories throughout your work-management system. This document need not be anything more than simple copy-&-paste of all your user stories and acceptance criteria. It can be maintained by the PO or the BA in the team.
- Technical architecture: Use your lead developer or the architect in the team to come up with this document to provide more visibility on the setup of the intended technical components of the application and how they interact with each other. Remember, having a running document of the overall architecture always comes in handy, contextually. It gets more ideas flowing and allows us to look for any gaps in the system.
- Development document: This is something developers can work on putting together. This document is intended to capture how the various components were coded. It does not need to be very detailed. The idea is to capture the highlights of the application, for example brief descriptions of any web services, stored procedures, jobs etc. used to create the system. Certain work-flows or sequence-diagrams could be added as well, if needed. This document comes in handy when there is a need to share knowledge across new team members. Using this document, before diving into understanding the code, just speeds up the process.
- Deployment document / operations manual: This document is nothing more than a step-by step guide written for the operator, who would be working on deploying the application from one environment to the other. If your deployment process is automated, then this is nothing more than a set of instructions on how to kickstart the deployment. If needed, this document will have instructions on any post-deployment operational tasks. The team (developers and testers) should work together to put this together.
- Test plan (functionality and performance): This is one of the most important documents. It is a summary of all your test cases and their results that indicate the level of testing that was done to certify the application. This could be auto-generated by some of the applications out there, such as MTM or QC.
I do want to emphasize again on the fact that none of these documents need to be extensive. Infact, when planning your work for the sprints, it is a good idea to plan some stories to put these documents together. This will help the team to be able to dedicate some time and be more focussed, while working on these documents.