This article briefly explains why documentation is required in development of software projects, what types of documents you should create and myth about agile documentation.
‘Working software over comprehensive documentation’ 2nd manifesto of agile software development (http://agilemanifesto.org/) . In traditional approach, you will find most of documents shown in Fig-01 are created before the development phase (coding) starts. The project starts with requirements phase, design phase etc each phase deliverables are just documents. Progress is ZERO until the coding phase starts. Documentation is not one time activity, you need to maintain it (update & reviewed) so more time & money spent. Sometimes project fails due to hefty documentation i.e. exceeding project budget or delay in completion.
Do we need really need all the listed documents? NO, Travel light. We get more business value in working software than in comprehensive (broader in scope) documentation.
Agile myth: Zero Documentation
Some believe that Agile doesn’t require (or, even, cannot support) documentation. Agile manifesto never says documents are waste or not useful. Agile documentation says: travel light (Write fewest documents), Just-in time, Update only when it hurts. You may save time & cost without documents but the project may fail in long run i.e. when the project is given to another team for maintenance. In simple words, no projects should be developed without supporting documents.
Why Do People Document?
- To support organizational memory
Working Software is Your Primary Goal. An important implication is that we not only need to develop software, but we also need to develop the supporting documentation required to use, operate, support, and maintain the software over time.
What type of documents do you need?
- Project Proposal
- Product Backlog: list of features to develop. Link features to use case doc
- Use case/User story/Feature Specs: covers
- Use case scenarios & screen prototype
- business rules & validation messages
- class diagram (nice to have)
- Design & Architecture document: consists of
- Technology, frameworks chosen for the projects
- Sequence diagram to explain execution flow
- Explanation on layers of architecture (mostly MVC2)
- How to develop & configure? Code snippets on view, controller, model, configuration files etc
- Non functional requirements
- Quality management:
- Defect tracker
- Functional test cases
- Build & Deployment document: covers
- System architecture/Deployment diagram
- Environment details e.g. IP details of DEV, TEST, UAT, PROD environments
- How to build & deploy?
- Labeling/Versioning strategy, SCM details
- Configuration Management details
- Post-deployment verifications
- Miscellaneous documents like
- Traceability matrix
I strongly encourage Product Owners to produce User Stories/Usecases/Functional Spec documents because they connect very deeply with the project, rest of the documents should be created & maintained by project team (Architects, Developers & Testers).