Literate Modeling—the Best of Both Worlds
LM supposes that for general business use, neither a pure narrative nor a pure visual language is sufficient for the reasons outlined above. LM solves both the encryption and trivialization problems by combining text and models.
In LM you embed model fragments in an explanatory narrative called a Business Context. The combination of the UML model and the Business Context is the Literate Model. This approach gives you the best of both worlds. The Business Context does the following:
- Decrypts the UML model for those who are non–UML-literate
- Highlights important business requirements that would otherwise be hidden in the UML model
- Contains embedded model fragments that give you the precision of UML
- Uses the same language as the UML model, giving you a consistent, controlled vocabulary for discussing the problem domain
Your primary goal in LM is that all stakeholders shall understand (and therefore be able to critique and validate) the Literate Model by reading the Business Context. Stakeholders with some UML knowledge will be able to read some of the embedded UML diagrams. Those who know UML well will be able to read the whole Literate Model. By this means, your Literate Model makes the information encoded in the UML model accessible to a very wide audience and bridges the gaps between the domain expert, analyst, designer and programmer.
To make this work, the Literate Model is subject to the several important constraints:
- At every level of reading, the Business Context must be consistent with itself.
- The Literate Model must be consistent with the business domain (otherwise it is not a model; it is a fantasy).
- The Business Context must be consistent with the UML model.
- The Business Context must use the language of the business domain so that it makes sense to non–UML-literate domain experts.
- The UML model must use the language of the business domain so that it is consistent with the Business Context. This is highly desirable—it is based on the principle of Convergent Engineering first stated by Taylor [Taylor 1].
Thus, the Business Context is not just a simple narrative—it is constrained in particular ways so that it can be mapped directly onto the UML model. We will look at precisely how you do this in the next section.