As you code and refactor, some of the software architecture documentation will become quickly obsolete and should be discarded. Use tools such as Maven, SchemaSpy, Doxygen, and UmlGraph to auto-generate up-to-date documentation from your source code. A wiki is also a good tool for publishing and sharing architecture documentation. For consistency, I recommend using a template for documenting the architecture.
Provide the documentation only if it is really needed and used by stakeholders. So, don't try to document everything. You do need to document the following:
- Design decisions and their rationale
- Design patterns and development frameworks used
- The architecture viewpoints and quality attributes that cannot be easily gleaned from the code alone.
Far too often, software architecture documentation only covers the code view. This is not enough. Stakeholders are not limited to developers, but also include end users, testers, the operational staff, compliance auditors, etc. When writing software architecture documentation, I first identify all stakeholders and their concerns. To ensure that I provide a 360-degree view of the architecture, I develop the architecture documentation based on the viewpoints and perspectives described by Nick Rozanski and Eoin Woods in their book "Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives" (Addison Wesley, April 2005)
The following are the Architecture Viewpoints:
- Functional
- Information
- Concurrency
- Development
- Deployment
- Operational
And here are the Architecture Perspectives:
- Security
- Performance and Scalability
- Availability and Resilience
- Evolution
- Accessibility
- Development Resource
- Internationalization
- Location
- Regulation
- Usability
These viewpoints and perspectives can be described using different notations such as UML (using stereotypes and profiles like SoaML for service oriented architecture), Business Process Modeling Notation (BPMN), and Domain Specific Languages (DSLs).
Posts
