Wednesday, October 13, 2010

Software Architecture Documentation in Agile Projects

One misconception that I often hear in Agile circles is that there is no need for software architecture documentation in Agile because "code is self-documenting". The emphasis in agile is not to eliminate the need for design and documentation, but to avoid Big Up Front Design (BDUF). Design and architecture documentation are still important in Agile. However, you only need just enough design and documentation to start coding. In other words, don't over-document.

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).