Documenting the AusStage Mapping Service

Documentation is a critical component of any development project and it is one which is often overlooked. This past week I’ve spent some time on exploring documentation options for the AusStage Mapping Service which I’m developing. I’ve focused primarily on the development aspects of the system so far.

The first aspect is to include appropriate comments in the Java code using the Javadoc syntax. The ant build script that I’m using, based on this sample one from the Apache Software Foundation, has provision for generating the documentation as one of its build targets. This documentation should be useful for other developers who would like to contribute to the project as it progresses.

The second aspect is to provide an overview of how the system is constructed and how it works. For this type of diagram I have used many different tools in the past but this time I’ve settled on the Visual Understanding Environment (VUE) from Tufts University. This software meets my three primary criteria:

1. Cross platform and preferably open source.
   VUE is written in Java and has distribution packages for Windows, MacOS, and Linux. The source code is also available and it is open source.
2. Be easy to use and support the development of complex diagrams.
   So far VUE has managed worked well with the diagrams I’ve created.
3. Develop diagrams that don’t require specialised knowledge to understand.
   This third criteria meant that I couldn’t use some of the more specialised packages such as those that created diagrams in the Unified Modeling Language (UML) standard.

The main diagram that I’ve created with the package so far is one that provides an overview of the components of the system, as well as an overview of the way data flows through the system. I currently exploring the idea of breaking this up into two separate diagrams. Particularly as the system gets more complex.

The most recent diagram can be seen below:

It will be interesting to see how the diagram evolves over time as the system is developed. I also plan on exploring some of the more advanced features of the VUE application to see how these types of diagrams can be enhanced.

As always I’ll post here as my explorations continue.

The photo “Another pile of accordion file folders” was uploaded to Flickr by Kasaa and used under the terms of a Creative Commons License.