Middleware

Simply following the Effective Analysis principles and implementing them using Enterprise Architect and Confluence will greatly improve the analysis and documentation effort in your organization. However, the approach is not complete without automating the manual tasks, as we have mentioned several times in the previous chapters.

Analysis and documentation outputs contain parts that should not be written but rather generated. Whether it is information that is very likely to change or a list of related elements from CASE, keeping them up to date manually in many places is inconvenient and a waste of time.

The same issue occurs for diagrams. Creating a diagram in Enterprise Architect and using it in Confluence requires exporting the image from EA and importing it to the page. Even though it is not a complex or time-consuming task, if it needs to be done a few dozen times in a row, it is very inconvenient. Besides, the manual import process will very likely cause inconsistency because we can never be sure that the diagram has been updated in all places.

Additionally, splitting the responsibilities between different tools can easily lead to duplication. Representing the CRM system as a component in Enterprise Architect and describing it using Confluence means there are two different versions of the same thing in two different places. This cannot be avoided, but the risk of duplication can be lowered using the automation tool.

Automation Tool

The solution to all the above problems is a "middleman" software that would automate the manual tasks, synchronize the repositories, and monitor the inconsistencies. We have been calling it middleware in the previous chapters.

The core function of the application is the automatic generation of artifact documentation pages. Since each artifact is represented by an element in Enterprise Architect and also by a Confluence page, a link must be first established between them. At the same time, the tool creates documentation page for the artifact, names it according to the predefined pattern and populates it with data according to the artifact template:

The application includes plenty of functions that will improve the way the analysis and documentation are done in your team. It automates tasks you have been doing manually so far and helps you work in the way which helps avoid inconsistency and duplication:

1. Generating and updating documentation parts in the page
   • Generating element attributes (e.g., name, version) and tagged values
   • Generating related elements (e.g., all classes connected to the element by dependency connector)
2. Inserting diagrams into the page
3. Generating diagram elements into the page
4. Generating a clickable map of diagrams for a composite diagram
5. Checking for inconsistencies
   • Warning when the artifact page is missing
   • Warning when the page title does not correspond to the pattern
6. Providing a tool for documenting user interface
7. Transferring changes from working EA repository to documentation EA repository

For more information regarding the tool, please refer to its homepage or check out the demo below to get a better idea about its capabilities and how it could make your team more effective in terms of analysis and documentation.