How to make your models available to a wide audience by automatically converting them into documents, posters or websites that are easy to distribute and understand.
As an aid to managing the complexity of their operations, many of our clients use visual models of their enterprise (business models, organizational structures and business processes, IT-systems). Often they invest thousands of hours and significant budgets into creating, maintaining and documenting these models.
Our experience shows that the information contained in these models is often used only by the few people in the company that know how to create and read these models – even though the information contained in these models would be useful for many people in the company.
To deal with this, some companies attempt to train more people to understand these models – but this is a time-consuming and costly approach that often fails because the people being trained aren’t really interested in learning about modeling languages and modeling tools.
If you think about it it is easy to understand why this approach fails – after all, training your employees to learn a modeling language and a modeling tool is a bit like forcing somebody to learn a new language just to read an important document – it is much better to simply translate the document, if necessary into multiple languages.
And this is exactly the approach we take when it comes to making models and their contents available to a wider audience: instead of helping the audience to understand the modeling language, we convert the model into something more understandable (such as documents, posters or even web-sites) and thus help them understand the contents of the model.
We at transentis have been helping clients to generate documents from models for many years – we generated our first “model-driven document” more then 10 years ago in 2001: A web-based process-oriented quality manual generated from an UML model that documented the companies business processes. Since then we have generated manifold documents, starting with simple spreadsheets to aid project managers, process manuals, IT-Specifications and even web-based enterprise architecture portals.
In this posting we would like to do three things:
- introduce the concept of model-driven documentation
- provide ideas on how to build a framework for model-driven documentation
- discuss the elements of creating a model-driven documentation process
The concept of model-driven documentation
The idea of model-driven documentation is very simple (but as we will discuss shortly, putting the idea into practice requires a great deal of discipline): instead of just creating a visual model and hoping that readers will understand it, it is better to:
- create the model using a visual modeling tool
- document that model entirely in the modeling tool
- generate a document from that model
In a corporate environment, the simple process illustrated above is only viable in small settings. We discuss why this is the case and how to amend the process in the section “Elements of a model-driven documentation process”.
Through this article the following model will be used as an example.
Now suppose you’d like to create a document from this model, that you can print out and hand to someone else, so that he or she can understand the system this model describes. You’d maybe want this document to start with an explanation about the purpose and scope of the model, then continue with a chapter describing all the components and interfaces and then continue with a chapter about the processes.
Fortunately, EA comes with a reporting feature. It let’s you convert the model into an RTF document, which can then be edited using a word processor. It allows the definition of templates for packages and elements, let’s you filter elements you don’t want to appear in the document and includes a huge number of additional settings.
Afterwards you can edit the generated document to include the introduction and modify the styling to comply to your company’s templates. You may also want to reorder the model element’s descriptions, if your desired arrangement is not already represented by the model’s tree structure.
If you’d for example like to include a chapter about all the messages and between which components they are sent, then you will have to add this chapter by hand. This is difficult (if not impossible) to achieve with the built-in generator. For each message you would have to find all channels it’s used in and then list both components, while maybe also filtering duplicate pairs.
The main drawback of this approach is that you will have to repeat all of the above steps each time you change something in the model and have to generate the document again. This makes the generation process unnecessarily slow and error-prone. For small changes made to the model, you could instead edit the RTF-document directly to resemble the change, but when the model’s structure is changed, this quickly gets out of hand.
We discuss how to remedy this situation in the next section.
A framework for model-driven documentation
When it comes to generating more complex documents we rarely rely on the generates that are provided with most modeling tools. Instead we use a “Model Exporter” that exports the model into a custom XML format.
For every document we want to generate from the model we then define one or a chain of several XSL-Transformations, that operate on the exported XML and generate into an appropriate document format:
- When creating traditional “long-text” documents (in PDF format) we have found the Docbook Framework to be very powerful.
- When creating spreadsheets we use the CSV format.
By replacing the built-in generator with a modular setup, the generation process can be improved in several ways:
- Using XML as an intermediary format makes it easily combinable with other sources such as requirements (which are often kept in a separate repository) or prose created with text editing tools
- Using XSLT to transform the XML into the Docbook format allows us to restructure the content and fully customize the look and formatting of the result
- Diagrams can be used in documents as vector based images, removing rasterization artifacts
- The entire process can be automated using scripts. Whenever the model is changed, you can create all documents instantly. To make generation really simple, Enterprise Architect includes an extensible “Tools” section, where the script’s executable can be added.
The process of this approach is illustrated in the diagram below. Your model is basically exported into an XML file, that resembles the XMI format. This XML file is then transformed into the Docbook format using an XSL file, that defines, which parts of your model are used for what parts of the resulting document. After that, another XSL transformation creates an FO file from the the Docbook file, bringing your company’s template into the result. The last step creates the actual PDF. It can be executed by and kind of FO processor, but we currently prefer Antenna House.
To make this process easier, we have created transentis Workbench. transentis Workbench is a small utility that makes the toolchain I illustrated above really simple to use – download the Workbench along with a sample model and give it a try.
Elements of a model-driven documentation process
When you introduce model-driven documentation in a project, it makes sense to first identify the different groups of readers and what informations they need. With this knowledge you can work on the outlines of the different documents. At the same time you can plan how the model should be structured and what UML elements should be used for what. In our experience this structure should at this point be written down as a metamodel. As soon as you believe to have a sound concept, the XSL transformations can be defined for each document.
When generating into the Docbook format you can benefit from having a central “customization layer” (comparable to a set of CSS files), that takes care of the look and formatting of all your generated documents. This way you just have to change this customization layer, when the company’s standard template changes.
As you become more and more familiar with generating documents from your model, you may start to move information from other sources into it, to maintain everything in a central place. As the model grows, you may require help from your team, e.g. to make bulk imports or large modifications in time. You will then have to brief your colleagues on how reality translates to your model and UML. It is important that they understand all of the model’s domain-specific details and apply them consistently.
EA supports this collaboration through version control. You can mark individual packages as version controlled, so that all changes to its contents are tracked and can be reversed. EA uses an exclusive locking mechanism, so that it’s not possible for two people to edit the same package simultaneously. This prevents accidental overwrites, but since elements can be connected across package borders, simultaneous edits in different packages can still break the model’s consistency.
In our experience every modeling team makes mistakes. Finding and correcting those manually in a big model is a tedious task, that has to be done every time the model is changed. Because you made the model your central location of information, it’s necessary to keep it at a high level of quality.
When we started supporting clients to maintain large models, we quickly saw the need for automated quality assurance. The idea is to translate the implicit and explicit rules of your model into a tool, that quickly finds and reports any inconsistencies. Just as an example: the latest version of our ModelChecker that is used by our client to check a model containing 10.000 Elements, 6000 connectors and 400 diagrams contains 30 rules. The ModelChecker takes less than 5 seconds to check this model and initially uncovered hundreds of mistakes. Adding it to EA’s “Tools” section makes it accessible with two clicks. Like having automated unit tests in a software development project, such a tool gives your team confidence to make substantial modifications without the fear of introducing hard-to-find errors.
Hopefully this post gave you an idea of how you could organize model driven documentation at your company. We are constantly improving our methods, so if you have any feedback, please leave a comment.