JavaZone 2009 - Tools and practices for agile architecture documentation

The problem
Creating good architecture documentation is often a problem in many large projects and organizations. Common issues are:
  • Out of date documentation in various MS Office formats
  • Architecture documentation is spread around the filesystem and mailsystem making it difficult to find the most current version of the documentation
  • Cumbersome and costly (enterprise) architecture tools
  • Using tools that are not well suited for multi-user updates
  • Developers are unwilling to document
  • Non-standard modelling conventions
  • Duplicated and inconsistent information
  • The list goes on...
The solution
A pragmatic and agile solution to most of these issues is to create a mashup of the Confluence wiki tool together with a UML tool like Sparx Enterprise Architect.
A wiki such as Confluence is very well suited for agile "grassroots" knowledge management and documentation. It keeps documentation in a single place, makes it easy for a group of people to work on the documentation together, it has a good search function, and it has proven to be a tool that most developers like to use.
A mashup integration of Confluence with the Enterprise Architect UML tool creates a powerful combination of two good tools. UML models are integrated in wiki pages, and the UML models will be updated automatically when the UML model is updated in the UML tool.
Other topics covered in the presentation:
  • using the Java API of Enterprise Architect to publish UML diagrams to Confluence
  • creating a 4+1 view model of architecture in a wiki
  • using labels to
    • organise the information and create views
    • express relationships between various parts of the architecture model
  • how to version control wiki documentation in Confluence
Per Spilling

Per Spilling

Per Spilling is a developer/architect/process mentor with 21 years experience in working with object technology (C++, Ada, Python, Actor, Concurrent C++, CORBA, Java). He is currently working as a principal consultant at Objectware in Oslo. His main work related interests are lightweight architectures, software craftsmanship, DDD, agile methods and agile development tools. Per has been a member of the JavaZone program committee for the last 5 years.