Modeling has been a hot topic for many years, with UML being one of the most popular ones. Models have many advantages: They provide structure, remove redundancies, and allow fancy things to be done with the model, even the generation of tests or code. We also sometimes model without even noticing: Software code represents also a (non-graphical) model, and the writer of requirements – with IBM Rational DOORS or formalmind Studio – is also building a requirements model.

Trends in Systems Engineering (German)

But first, as a service to our German readers, the list of articles since the last newsletter on our companion blog, SE-Trends:

• Ist agiles Systems Engineering möglich?
• Von der Anforderung zum Modell
• Mit Effizienz an der falschen Sache arbeiten
• Warum wir beim Modellieren zwischen Lesen und Schreiben unterscheiden müssen
• Wie Systemdenken die Todesrate in der Chirurgie fast halbiert hat
• Interview mit Tim Weilkiens zu SysML
• Schafft Daimler die Einführung von Model-Based Systems Engineering (MBSE)?

If you speak German, please check it out, and please forward this to interested friends and colleagues. Visit SE-Trends >>

Back to Modeling

While geeks appreciate models, many people shy away from them, as they can be intimidating. This is the reason why document generation is a very important topic: A carefully tailored document generator  can make the difference between acceptance or rejection by the stakeholders.

To understand this, we have to remember that we can separate stakeholders in broadly two groups: Those who author models and those who read them. The first group is usually much smaller than the later. And there is rarely a need to confront the readers with the modeling tools at all.

Reading vs. Writing Models

Creating Models is hard. Creating high-quality models is even harder. It takes a lot of effort and lots of experience, and requires not only the mastery of the modeling language, but also of the methods, patterns and tools. For the modeling effort to succeed, it is crucial to have at least one experienced modeler in the team, who can act as the mentor and coach to the junior modelers. But the total number of modelers is usually small, compared to the team as a whole.

Reading Models is much easier. The most important aspect is to master the language elements and to be able to understand their meaning. For instance, people have been drawing boxes and arrows forever. But in UML there are a small number of different arrows with distinct meanings. It is important that the readers understand the differences.

Training

Another take-away of this insight are the consequences for training: Readers and writers must be trained differently, for two reasons: First, teaching to read is much faster than teaching how to model. And there are usually many more readers than writers. For cost reasons alone it makes sense to give the many readers a shorter reading-lecture, while the writers have to take the longer modeling lecture.

The second reason is frustration: Readers include non- or moderately-technical people like project managers, customers, and so on. Making these people sit through a class that they are not that interested in, and that may even leave them behind, is counter-productive. It may make them reject the project before it has even started. Therefore, all the readers need is a short crash course that should not be longer than a day.

Realizing that the two groups need different training raises the question of the scope of the training. The writers need to learn how to use the modeling tool as well, although these could be separate trainings as well – especially in the beginning, a tool can be too distracting. The basics of modeling can also be learned on a whiteboard. But do the readers even have to know the tool? We don’t think so.

Documents

Most models can be consumed on paper, and don’t require a tool at all. This is certainly true for UML models. There are some models that benefit from being viewed in a tool, like 3D-sketches. But even in those cases, there may be a lightweight viewer available that does not overwhelm the reader with too many distracting user interface controls.

But this also means that the document generation is fairly important, again for a number of reasons: First, we do not want to frustrate the readers, most of whom probably have little experience reading models, beyond the crash course they received. Therefore, the documents should be as intuitive as the modeling language allows them to be.

Second, the modelers must be prepared to get frequent requests for updated documents, generated from the model. Therefore, it must not take long to generate them. For larger projects it may even be sensible to set up a continuous integration system that automatically generates the most frequently used documents either on demand, or on an hourly or daily basis.

Bottom Line

Stop thinking about documents as paper: They are “read-only views on your model”, using a technology (paper) that is familiar to all stakeholders. As a bonus, it even comes with a built-in commenting system (pen and text marker). If you look at things this way, you’ll keep your stakeholders happy and informed, while your project can benefit from the power of modeling.