Documenting the architectures is very important for many different reasons. Some of the reasons are cited below:
- To convey the system architecture to the developers of the system so that they understand the rationale behind some of the decisions taken
- To communicate the system evolution information to different stake holders of the system
- Documentation of some of the key architectural decision have a far reaching effect during its enhancement and maintenence phases
- Documentation of not just the final architecture but also the alternative architecture gives the rationale behind the selection of current architecture
- Provides a common reference for discussions and understanding the system
- Sets down some of the ‘rules’ to be followed to get the correct system behavior
- Provides information( services provided by the system ) to system integrators who want to integrate your system with other systems
- Provides the basis for planning for managers(basis for WBS )
- Provides basis for forming team structures
- It is the primary basis for assessing the system performance even before it is built
- It sets some the constraints, limitations on the product/project requirements
- It is the place where make vs decisions is made and is documented
While I may have missed some of the other benefits, it easy to derive them from the points given above. Since many people use UML modeling tools for documenting their architecture, it has some drwbacks:
- It is easy to miss the rational behind some of the architectural decisions
- Not easy to document alternative architectures
- Not easy to capture some of the architecture rules, guidelines mandated by the architecture
- Heavy use of UML constructs and the lack of understanding of UML deters some of stake holders from using them
Hence it is better to capture the architecture in a word document. UML notation may be used for describing the architecture and supporting text describes the diagrams un ambiguously. Good architectures always provide enough flexibility for improvements and innovations and does not prescribe rigid rules. This allows architecture to evolve over time without much ill-effects. Hence the the architecture document describes just enough information.
While I have tired to list the importance of documentation, how to document effectively is not discussed here. For more information on effective documentation please refer to SEI’s - Software Architecture Documentation In Practice
