Challenges with old-style software architecture documentation
Keeping architecture models and textual documentation up to date is often a challenge, especially if you are creating old-style documentation with MS Word etc. Documentation in MS Word is difficult to edit concurrently by more than one person, and documents are often passed around in emails, which may create confusion about where the “master” documentation can be found. Searching for documentation is often also a problem.
A better way
A better way is to use web-based wikis, like Confluence. A wiki lends itself very well to collaborative documentation. Likewise, in order to collaborate on architecture models it is preferable to use a repository-based UML tool. So, one optimal solution would be to combine Confluence with a repository-based UML tool, as shown in the following illustration:
A good UML tool that support using a model repository for collaborative development of architecture models is Sparx Enterprise Architect. But how can we combine Confluence and Enterprise Architect in an effective manner?
Well, it turns out that Confluence has a feature that makes it easy to create a mashup solution where the images are located on an external web server. Images are included in a wiki page with the exclamation mark notation, like this:
So, the next step is to find a way to export the models from Enterprise Architect as images and place them on a web server so that they can be embedded in Confluence pages. You can export the models as images from Enterprise Architect via the “Generate HTML Report” function:
However, a problem with this export function is that the images are given random names that have no connection with the model names. Similarly for the directory names where the images are placed:
What makes it even worse is that the images might get new random names the next time you do an export from Enterprise Architect.
Luckily there is another, albeit fairly complex, way to export model diagrams from Enterprise Architect - via the provided API. The API can be used by either Java, VB or C# programs. In our case we decided to make a little Java program and create the following solution:
So after some coding we found out that we where able to export diagrams with their model-names and hierarchy structure as shown here:
This made it possible to achieve the following:
- Extract model diagrams as images for inclusion in Confluence wiki pages
- Give the diagrams fixed, and logical file names based on their name in the UML model
- With the fixed logical file names we were able to re-generate the images via a command line script when the model was changed in the UML tool, and thus automatically update the diagrams on the wiki pages.
An effective solution for agile architecture documentation :-)
A lightning talk about this work was given at the JavaZone conference in 2009. The slides from the
talk are found here: Agile documentation with Confluence and Sparx Enterprise Architect.
Take a look at the slides for more details about how we used used
EaDiagramGenerator to integrate Confluence and
Enterprise Architect, and useful macros and techniques for structuring documentation in Confluence.
The source code for the diagram export tool is available on GitHub: https://github.com/perspilling/eatools.
Credit: The EaDiagramGenerator tool was created together with Ove Scheel.
The last couple of years we have seen improved drawing tool plugins for Confluence, and nowadays I usually use Gliffy for architecture and business process diagrams. Gliffy is not a real UML modelling tool like Enterprise Architect, but it is a good sketching tool, and being so well integrated with Confluence is a big advantage. Another advantage compared to using Enterprise Architect is that is a web-based tool running on all platforms, while Enterprise Architect only runs on MS-Windows.
Another diagramming plugin for Confluence is Lucidchart. I haven’t tried it myself, but it seems to be a very good sketching tool.