transentis consulting

Introduction to Model-driven Documentation

Automatically generate documents and websites from Enterprise Architecture Models
  • Robert Pagel
    Robert Pagel
    Monday, December 3, 2012
An overview of how to make Enterprise Architect models available to a wide audience by automatically converting them into documents, posters or websites
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 are not 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 than 10 years ago in 2001: A web-based process-oriented quality manual generated from a 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
  • a document that models 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.
Example of a Model
Model-driven documentation is not bound to any particular modeling tool, but we chose ®Enterprise Architect (EA) from our partner Sparx Systems for this example. This model describes a system of several components and their interactions with each other. It uses classic UML, but in addition, we introduce a domain-specific way of modeling – the interactions between components are modeled on two levels:
  • The high level describes “corridors”. Corridors exist between components, that communicate directly with each other. They are modeled using UML-Associations between components. Each corridor has a unique ID as its name.
  • On the lower level, the corridors are replaced by sets of “channels”. Channels are modeled as UML-InformationFlows between exposed interfaces of components. Each channel resembles the flow of at least one message. This way of modeling hides information when you view the “big picture” (imagine the above diagram with dozens of components) while allowing you to zoom into the communication details.
Our example describes four central components of an internet archive. The web frontend is used to access the content inside the archive and query the search index, while the crawler is responsible for adding new content. The “big picture” as explained above looks like this:
In addition to these components and their interfaces, processes are modeled as well, to describe the logic behind the system’s interactions. We use activity diagrams for this. For each component involved, each process contains a partition. Partitions in turn contain actions. Actions are usually connected through control flows, but when both actions belong to different partitions, an object flow has to be used, representing the sending of a message.
Your model is probably much bigger, contains different diagrams and has other domain-specific features. However, the documentation process illustrated in this post works with any kind of model.
Now suppose you would 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 would 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 lets 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, lets you filter elements you do not want to appear in the document and includes a huge number of additional settings.
Afterward, you can edit the generated document to include the introduction and modify the styling to comply with 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 would 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 is 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 LaTeX-like Docbook Framework to be very powerful.
  • When creating web-based views we use HTML5 and CSS3 for the structure and style of the website, Javascript for the dynamic behavior and encode the content from the model using JSON.
  • 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 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.

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 their contents are tracked and can be reversed. EA uses an exclusive locking mechanism so that it is 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 is 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 me a message.
Upcoming Events

Economics of Analytics And Digitization

2 hours - 2021-12-16

Modeling Growth Strategies For Professional Service Firms

2 hours - 2022-01-27

Data-Driven Enterprise Architecture Management

2 hours - 2022-02-24

Go to event overview

Recent Blogposts

Simulating The Beer Game

Oliver Grasl - 2021-11-16

Introduction to The Business Prototyping Toolkit

Oliver Grasl - 2021-08-17

Using ArchiMate to Brainstorm Enterprise Architectures

Olga Medvedeva - 2021-04-28

Go to blog overview

Email newsletter

Subscribe to our newsletter and stay up to date about the latest trends and news.

Name
Email
Subscribe to our newsletter and stay up to date about the latest trends and news.
  • transentis
Contact us

transentis consulting

Geisbergstraße 9

10777 Berlin


+49 30 9203833320

info@transentis.com