Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Literate Modeling—Technique
The model and Business Context are carefully tied together by a common set of terms, which are the names of UML model elements. This interweaving of the narrative and model is the key technique that generates the mapping between the Business Context and its associated UML model. It is the essence of LM.
You should extract the set of terms into a glossary that contains the following information:
|
Term |
|
IsPrimary |
|
Definition |
|
Model element |
|
Synonyms |
Here is an example of a glossary entry:
|
Term: emailAddress |
|
IsPrimary: true |
|
Definition: The email address of a Person. |
|
Model element: Person::emailAddress |
|
Synonyms: electronicAddress |
This glossary creates a controlled vocabulary for your project that greatly aids communication. For example, in LM when someone talks about a Person, you know exactly and precisely what it means because there is a definition in the glossary, a description in the Business Context, and a UML model.
Each glossary entry has an isPrimary flag. Primary terms are those used within your project and might have corresponding model elements. Glossary Entries might have zero or more synonyms. You often encounter synonyms when one part of the business uses one term for something and another uses a different term with the same meaning. In this case, you choose one term as the primary term. This is the term that you will use throughout your project and in your UML models. The other variants are synonyms that can be used in particular parts of the business or to communicate with particular stakeholders. Here is an example of a synonym for emailAddress:
|
Term: electronicAddress |
|
IsPrimary: false |
|
Definition: see emailAddress |
|
Model element: none |
|
Synonyms: none |
Synonyms by definition have no associated model element. Model elements can be associated only with primary terms.
In LM if something has no value, you write "none." Never leave the field blank because this might mean either that it has no value or that you just haven’t thought about it yet.
Terms are highlighted in the Business Context using some sort of typographical convention such as a color or a font. This is necessary because some terms such as "address" could merely be the word "address," or they could indicate the address attribute of a class in the model. You need to distinguish very clearly between these two usages of the word. I find that it’s easiest to do this typographically. A good strategy is to define a character style for the terms and then you can write macros to extract them from the text and check them for consistency against the UML model—and so on. Any highlighted term used in the text that is not in the model might be an error.
Terms are "humanized" to make them more readable. This involves the correct use of plurals and apostrophes so that, for example, Person becomes Person’s or People where appropriate. However, the case of the term (lowerCamelCase or UpperCamelCase) does not change. Clearly, this complicates the mapping to the model, but it is essential to make the Business Context readable. Ruby On Rails uses a similar set of naming conventions to tie models to database tables and contains a useful set of tools for Literate Modelers! The essential point is that a term in the Business Context must be easily traceable back to the corresponding element of the UML model, and vice versa.
The figure below shows an excerpt from a larger Literate Model for Money described in [Arlow 2]. Notice that the text is tied to the model. Terms from the model are, in this case, highlighted in the text using a color.
)
Here is a summary of the key points for Business Contexts:
- The narrative refers to one or more specific UML model elements—you can refer to any model element that has a name.
- The names of all model elements are written in a special style.
- Use plurals where necessary—so if you need to talk about more than one Locale, you use the term Locales.
- Use apostrophes appropriately—for example, you can talk about a Currency’s Locale.
- The text reads well and is comprehensible whether the UML model is present or not.
The last point is very important. The text should be comprehensible whether you can read the UML model or not. In fact, a good test of a business context document is to cover up all the UML models and see if it is still readable. It should be!