Increase the Accessibility and Comprehensibility of a Visual Model with Literate Modeling
- Encryption of Business Requirements and Semantics
- Trivialization of Business Requirements
- Literate Modelingthe Best of Both Worlds
- Literate ModelingTechnique
- Structuring the Business Context
- When to Use Literate Modeling
- Where Can I Learn More?
- Bibliography
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Literate Modeling (LM) is a way of increasing the accessibility and comprehensibility of a visual model by embedding it in an explanatory narrative.
The technique was discovered in 1999 and first described in [Arlow 1]. I’m careful to say "discovered" rather than "created" because on publication of the paper I received many emails from modelers saying that they had been using LM for some time without knowing what to call it! As such, LM merely reflects the best practice of experienced modelers rather than any particularly new technique.
In this article, I’ll consider LM applied to UML models, but you should bear in mind that the technique is applicable to any visual modeling language.
Essentially, what you are doing in LM is tying your UML model, precisely and consistently, to a narrative description of the business domain called a Business Context. This deceptively simple strategy has very significant benefits that will become more and more apparent to you with each Literate Model you create:
- Your UML models will be greatly improved because many more people can understand them and review them.
- Writing the Business Context demands that you to understand the business domain deeply. Obviously, this will also improve your models.
- The Business Context will highlight omissions and mistakes in the UML model. Something that might look OK in UML might turn out to be wrong when described in the Business Context.
- As you will see in the next section, LM creates a controlled vocabulary that gives you a consistent and correct way of talking about the business in your project.
- You can achieve very high levels of consistency in both your Business Context and UML model by virtue of them one correcting and refining the other.
The bottom line is that LM makes you a better modeler!
In the next couple of sections, we will look at some problems with visual languages and some reasons why LM is needed.
Encryption of Business Requirements and Semantics
There is a common belief that visual languages are in some way more easily understandable than text—hence the saying "a picture is worth a thousand words."
The superiority of pictures for certain types of communication was certainly one of the driving forces for the creation of UML. There was a broad consensus in the software industry that a visual representation of a software system would be more precise than a narrative description and yet more accessible and comprehensible than the source code. Perhaps more importantly, pictures allow the system to be visualized at many different levels of abstraction before committing time and resources to create the source code at the lowest level of abstraction.
Although the UML has been a great boon to analysts and designers, it’s important to realize that in some circumstances pictures don’t clarify at all—they obscure. Visual languages such as UML express key business requirements and semantics in a complex visual syntax that is comprehensible only to those who understand the language. With regard to UML, key business requirements and semantics become captured, encoded and, for those who don’t know UML, encrypted in models. This realization was our point of departure in our initial paper on LM [Arlow 1]; that from the perspective of the majority of the stakeholders on a typical UML project, key business requirements and semantics are encrypted in the UML models. In [Arlow 1] and [Arlow 2], we examined the various UML diagram types and assigned a tentative comprehensibility to them for the different types of stakeholders.
Encryption presents the analyst with a fundamental issue of traceability. Information tends to flow one way from the non–UML-aware stakeholders to the UML-aware modelers becoming encrypted in the process. The UML work products of the analysts are only partially and imperfectly comprehended by the majority of the stakeholders. This means that the non–UML-aware stakeholders can’t easily check and validate the UML models. This is a very big problem because it is generally the stakeholders that have the best understanding of the business domain.
Encryption is a problem whenever a UML model needs to be understood by someone who only partially understands UML. Many programmers have trouble understanding the full implications of a UML model because their knowledge of UML is incomplete. This can have a very negative impact on how they realize the model in code. Similarly, many modelers have difficulty producing precise UML models because although they understand UML syntax, they might not completely understand the underlying UML semantics or use it in an idiomatic way. This is amply demonstrated by many of the books on UML.