From eb98a4b363cab5cf867797d52e84d5743c35e067 Mon Sep 17 00:00:00 2001 From: Zimmermann Olaf Date: Mon, 23 Mar 2020 11:50:02 +0100 Subject: [PATCH 1/9] Improved paper and presentation links --- _docs/tutorials/event-sourcing-and-cqrs-modeling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_docs/tutorials/event-sourcing-and-cqrs-modeling.md b/_docs/tutorials/event-sourcing-and-cqrs-modeling.md index 81e301f..193f062 100644 --- a/_docs/tutorials/event-sourcing-and-cqrs-modeling.md +++ b/_docs/tutorials/event-sourcing-and-cqrs-modeling.md @@ -152,6 +152,6 @@ However, the DSL syntax itself does not need additional concepts to support it. ## Other Tutorials and Links * Tutorial: [Document Event Storming Results with Context Mapper](/docs/event-storming/) - * [Domain-specific Language and Tools for Strategic Domain-driven Design, Context Mapping and Bounded Context Modeling](https://doi.org/10.5220/0008910502990306) - * [Context Mapper: DSL and Tools for Domain-Driven Service Design - Bounded Context Modeling and Microservice Decomposition](https://contextmapper.org/media/ZIOSK-ContextMapper4JUGv10p.pdf) + * Presentation on Context Mapper:[Context Mapper: DSL and Tools for Domain-Driven Service Design - Bounded Context Modeling and Microservice Decomposition](https://contextmapper.org/media/ZIOSK-ContextMapper4JUGv10p.pdf) + * Paper introducing the Context Mapper DSL (CML): [Domain-specific Language and Tools for Strategic Domain-driven Design, Context Mapping and Bounded Context Modeling](https://doi.org/10.5220/0008910502990306) From 69e4f64a3f49f0b35d93431afc038e166444444e Mon Sep 17 00:00:00 2001 From: Zimmermann Olaf Date: Mon, 23 Mar 2020 12:19:19 +0100 Subject: [PATCH 2/9] Service Cutter page, Discovery Library page edits --- .../reverse-engineering.md | 39 +++++----------- .../service-cutter/context-map-suggestions.md | 45 +++++++------------ .../event-sourcing-and-cqrs-modeling.md | 8 ++-- 3 files changed, 34 insertions(+), 58 deletions(-) diff --git a/_docs/reverse-engineering/reverse-engineering.md b/_docs/reverse-engineering/reverse-engineering.md index 3a54601..a17414c 100644 --- a/_docs/reverse-engineering/reverse-engineering.md +++ b/_docs/reverse-engineering/reverse-engineering.md @@ -3,34 +3,25 @@ title: Context Map Discovery permalink: /docs/reverse-engineering/ --- -Our "context map discovery" or "reverse engineering" library allows to derive a CML context map from existing source code. If you work in a project -with an existing monolith you may want to generate a CML Bounded Context with your domain model. Afterwards, you can analyze and decompose the architecture -with our tools. This simplifies the start with our tool and avoids huge efforts to re-model the existing system. If your system already has -a (micro-)service-oriented architecture you may want to reverse engineer the CML context map illustrating all bounded contexts and their relationships. +Our "context map discovery" or "reverse engineering" library allows you to derive a CML context map from existing source code. If you work in a project involving an existing monolith, you may want to generate a Bounded Context that represents and contains your domain model. Afterwards, you can analyze and decompose the architecture with our tools. This helps you to get started with our tool and avoids huge efforts to re-model the existing system. If your system already has a (micro-)service-oriented architecture, you may want to reverse engineer the CML context map illustrating all bounded contexts and their relationships. -The discovery library supports to reverse engineer bounded contexts and context maps (relationships between bounded contexts). It is extensible and -designed to plug-in new discovery strategies. The current prototype supports bounded context discovery for Spring Boot applications and relationship -discovery on the basis of Docker compose. +The discovery library supports the reverse engineering of bounded contexts and context maps (including relationships between bounded contexts). It is extensible and designed to plug-in new discovery [strategies](https://en.wikipedia.org/wiki/Strategy_pattern). The current prototype supports bounded context discovery for [Spring Boot ](https://spring.io/projects/spring-boot) applications and relationship discovery on the basis of Docker compose. -Contributions to the discovery library are very welcome! If you implement a new discovery strategy for another programming language or framework, please -contribute it to our project and create a PR in our [Github repository](https://github.com/ContextMapper/context-map-discovery). +Contributions to the discovery library are very welcome! If you implement a new discovery strategy for another programming language or framework, please contribute it to our project and create a Pull Request (PR) in our [GitHub repository](https://github.com/ContextMapper/context-map-discovery). ## Usage The latest version of the discovery library is available through Maven Central: [![Maven Central](https://img.shields.io/maven-central/v/org.contextmapper/context-map-discovery.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22org.contextmapper%22%20AND%20a:%22context-map-discovery%22) -You can find all information about the library, how to use it and how to extend it with new discovery strategies, in our Github repository: +You can find all information about the library, how to use it, and how to extend it with new discovery strategies in our Github repository: [https://github.com/ContextMapper/context-map-discovery](https://github.com/ContextMapper/context-map-discovery) -Note that this is a prototype and limited in the discovery strategies already implemented. New strategies have to be implemented in the future. +Note that this is a prototype and limited in the discovery strategies already implemented. Additional strategies will have to be implemented in the future. ## Lakeside Mutual Case Study -The following example illustrates how the discovery library works. We applied it to the [Lakeside Mutual](https://github.com/Microservice-API-Patterns/LakesideMutual) -project, a fictitious insurance company. It is a sample application to demonstrate microservices. With our -[context map discovery library](https://github.com/ContextMapper/context-map-discovery) we derived a CML context map from the -[Lakeside Mutual source code](https://github.com/Microservice-API-Patterns/LakesideMutual). +The following example illustrates how the discovery library works. We applied it to the [Lakeside Mutual](https://github.com/Microservice-API-Patterns/LakesideMutual) project, a fictitious insurance company. It is a sample application to demonstrate microservices. With our [context map discovery library](https://github.com/ContextMapper/context-map-discovery) we derived a CML context map from the [Lakeside Mutual source code](https://github.com/Microservice-API-Patterns/LakesideMutual). -The following diagram provided by the project itself illustrates the architecture: +The following diagram, courtesy of the Lakeside Mutual project itself, illustrates the architecture: ![Lakeside Mutual Architecture Overview](/img/lakeside-mutual-overview.png) @@ -43,7 +34,7 @@ With the [strategies already available](https://github.com/ContextMapper/context The _risk management context_ is currently not detected, since a strategy on the basis of Node.js is not available yet. -The following piece of code is all which is needed to generate the context map with our library: +The following piece of code is all that is needed to generate the context map with our discovery library: ```java public class LakesideMutualContextMapDiscoverer { @@ -76,15 +67,10 @@ public class LakesideMutualContextMapDiscoverer { } ``` -The library is based on strategies implementing the three interfaces `BoundedContextDiscoveryStrategy`, `RelationshipDiscoveryStrategy`, and -`BoundedContextNameMappingStrategy`. The `BoundedContextNameMappingStrategy` strategy can be used to map different bounded context names between the -bounded context and relationship strategies. +The library is based on strategies implementing the three interfaces `BoundedContextDiscoveryStrategy`, `RelationshipDiscoveryStrategy`, and `BoundedContextNameMappingStrategy`. The `BoundedContextNameMappingStrategy` strategy can be used to map different bounded context names between the bounded context and relationship strategies. -In this example we use the `SpringBootBoundedContextDiscoveryStrategy` to discover the bounded contexts on the basis of Spring annotations. It -derives bounded contexts from applications, aggregates from REST endpoints, and Entities from the REST endpoint methods. The -`DockerComposeRelationshipDiscoveryStrategy` strategy is used to derive the relationships between the bounded context from the docker-compose.yml file. -The extended `SeparatorToCamelCaseBoundedContextNameMappingStrategy` in the example above is used to map names such as 'customer-management-backend' -(name according to relationship strategy) to 'CustomerManagement' (name according the discovered bounded context). +In this example we use the `SpringBootBoundedContextDiscoveryStrategy` to discover the bounded contexts via Spring annotations. It +derives [Bounded Contexts](https://github.com/ContextMapper/language-reference/bounded_context) from applications, [Aggregates]((../language-reference/aggregate)) from REST endpoints, and Entities from the REST endpoint methods. The `DockerComposeRelationshipDiscoveryStrategy` strategy is used to derive the relationships between the bounded context from the `docker-compose.yml` file. The extended `SeparatorToCamelCaseBoundedContextNameMappingStrategy` in the example above is used to map names such as 'customer-management-backend' (name according to relationship strategy) to 'CustomerManagement' (name according the discovered bounded context). The code above creates the following context map for the application: @@ -171,5 +157,4 @@ The code above creates the following context map for the application: } -We removed the entities in the CML model above in order to save space here. The full example and the projects source code can be found -[here](https://github.com/ContextMapper/context-map-discovery/tree/master/Examples/LakesideMutual). +Note that we removed the entities in the CML model above in order to save space here. The full example and the project source code can be found [here](https://github.com/ContextMapper/context-map-discovery/tree/master/Examples/LakesideMutual). diff --git a/_docs/service-cutter/context-map-suggestions.md b/_docs/service-cutter/context-map-suggestions.md index c294c5f..945d636 100644 --- a/_docs/service-cutter/context-map-suggestions.md +++ b/_docs/service-cutter/context-map-suggestions.md @@ -3,58 +3,47 @@ title: Context Map Suggestions with Service Cutter permalink: /docs/service-cutter-context-map-suggestions/ --- -The [Service Cutter](http://servicecutter.github.io/) tool offers a structured way to service decomposition. It creates suggestions how a system -could be decomposed into services on the basis of [coupling criteria](https://github.com/ServiceCutter/ServiceCutter/wiki/Coupling-Criteria) and -graph clustering algorithms. +The [Service Cutter](http://servicecutter.github.io/) tool proposes a structured way to service decomposition. It suggests how a system could be decomposed into services according to 14 prioritized [coupling criteria](https://github.com/ServiceCutter/ServiceCutter/wiki/Coupling-Criteria). Domain model elements are required as input. The tool then applies graph clustering algorithms to identify possible *service cuts*, which are returned as output. ## Context Mapper Integration -With our [Service Cutter library](https://github.com/ContextMapper/service-cutter-library) which is a fork of the original -[Service Cutter](https://github.com/ServiceCutter/ServiceCutter) we integrated the structured decomposition approach into Context Mapper. It allows -you to generate new decomposition suggestions in the form of CML Context Maps. The decompositions are derived on the basis of the original -[coupling criteria catalog](https://github.com/ServiceCutter/ServiceCutter/wiki/Coupling-Criteria). +We provide a [Service Cutter library](https://github.com/ContextMapper/service-cutter-library), which is a fork of the original +[Service Cutter](https://github.com/ServiceCutter/ServiceCutter), to be able to offer its structured decomposition approach in Context Mapper. The library allows you to generate new decomposition suggestions in the form of CML Context Maps. The decompositions are derived from the original [coupling criteria catalog](https://github.com/ServiceCutter/ServiceCutter/wiki/Coupling-Criteria). -Once you have modeled your system in [CML](/docs/language-reference/) or [discovered it from existing code](/docs/reverse-engineering/) -you can generate new decomposition suggestions or _service cuts_ by using the following context menu entry: +Once you have modeled your system in [CML](/docs/language-reference/) or [discovered it from existing code](/docs/reverse-engineering/), you can generate new decomposition suggestions or _service cuts_ by using the following context menu entry: ![Generate New Service Cuts (Context Menu)](/img/service-cut-generator-context-menu.png) ### Input and Preconditions -Service Cutter needs the system to be described in entities and so-called nanoentities. This structure is automatically derived from your CML model. -In addition, you can provide user representations (use cases etc.) to improve the quality of the cuts. Thus, you can generate new Context Maps -describing service decompositions with the following input: +Service Cutter needs the system to be described in entities and so-called *nanoentities*. This structure is automatically derived from your CML model. In addition, you can provide user representations (use cases etc.) to improve the quality of the cuts. Thus, you can generate new Context Maps describing service decompositions with the following input: * CML file describing your system - * **Optionally:** User descriptions in form of a SCL (Service Cutter language) file. + * **Optionally:** User descriptions in form of a SCL (Service Cutter Language) file. * You can find out [here](/docs/service-cutter/) how to create such file. -The following **preconditions** have to be fulfilled so that we are able to derive the structure (ERD) required by Service Cutter: +The following **preconditions** have to be fulfilled so that we are able to derive the structure required by Service Cutter (called ERD): - * Your CML model must describe the Bounded Contexts including entities and attributes. - * Without attributes we cannot derive nanoentities and Service Cutter cannot calculate decompositions. + * Your CML model must include Bounded Contexts with entities and attributes. + * Without attributes, we cannot derive nanoentities and Service Cutter cannot calculate decompositions. -Note that if the _Leung_ algorithm is used, the decompositions can be different every time the generator is called (non-deterministic algorithm). +Note that if the _Leung_ algorithm is used, the decompositions can be different every time the generator is called (it is a non-deterministic algorithm). ### Solver Configuration A dialog will allow you to configure the following inputs needed by Service Cutter: - * **The algorithm**: Currently we only provide one algorithm, but others will be added in future releases (the _Girvan-Newman_ algorithm - supported by Service Cutter cannot be integrated into Context Mapper due to licence issues). - * **Coupling criteria priorities**: You can customize the priority of each coupling criterion, as you can do it in Service Cutter. - * **User representations (optional)**: The user representations can be provided with our SCL (Service Cutter Language) DSL. [Here](/docs/service-cutter/#generate-scl-file) - you can find out how to create/generate such a file. + * **The algorithm**: Currently we only provide one algorithm, but others are forseen to be added in future releases (note that the _Girvan-Newman_ algorithm supported by Service Cutter cannot be integrated into Context Mapper due to licence issues). + * **Coupling criteria priorities**: You can customize the priority of each coupling criterion, as you can in Service Cutter. + * **User representations (optional)**: The user representations can be provided with our SCL (Service Cutter Language) DSL. You can find out how to create/generate such a file [here](/docs/service-cutter/#generate-scl-file). ![Service Cut Generator Dialog](/img/service-cut-generator-dialog.png) ### Example Result -By finishing the wizard illustrated above Context Mapper will create a new CML file with a new decomposition suggestion. Note that the _Leung_ algorithm -is _non-deterministic_ and will derive new decompositions every time you execute it. This is an example decomposition generated for the +When finishing the wizard illustrated above, Context Mapper will create a new CML file with a new decomposition suggestion. Note that the Leung algorithm is non-deterministic and will derive new decompositions every time you execute it. +This is *one* example decomposition generated for the [DDD cargo sample application](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/ddd-sample): ![Service Cut Generator Example Result (DDD Cargo sample application)](/img/service-cut-generator-ddd-sample-result.png) -Please note that the resulting model does not contain the original data types. We currently loose this information through the cutting process. However, -the results still show how the entities are mapped to Bounded Contexts and how the single attributes are mapped to the entities. +*Known limitation*: Please note that the resulting model does not contain the original data types. We currently loose this information through the cutting process. However, the results still show how the entities are mapped to Bounded Contexts and how the single attributes are mapped to the entities. ## Service Cutter Input File Generators -If you want to work with the original [Service Cutter](http://servicecutter.github.io/) tool you can also use our -[Service Cutter generators](/docs/service-cutter/) to derive the needed input files in the JSON format from your Context Map. +If you want to work with the original [Service Cutter](http://servicecutter.github.io/) tool, a [JHipster](https://www.jhipster.tech/) application, you can also use our [Service Cutter generators](/docs/service-cutter/) to derive the needed input files in the JSON format from your Context Map. Simply save them here (in Context Mapper) and upload them there (in the original Service Cutter). diff --git a/_docs/tutorials/event-sourcing-and-cqrs-modeling.md b/_docs/tutorials/event-sourcing-and-cqrs-modeling.md index 193f062..2896d8d 100644 --- a/_docs/tutorials/event-sourcing-and-cqrs-modeling.md +++ b/_docs/tutorials/event-sourcing-and-cqrs-modeling.md @@ -17,8 +17,10 @@ If you are not fully familiar with the concepts of event sourcing and CQRS yet, * [Developing Transactional Microservices Using Aggregates, Event Sourcing and CQRS](https://www.infoq.com/articles/microservices-aggregates-events-cqrs-part-1-richardson/) by Chris Richardson * [Designing Event Sourced Microservices](https://www.infoq.com/news/2017/11/event-sourcing-microservices/) by Jan Stenberg -## Modeling in Context Mapper -This page highlights the [Context Mapper DSL (CML)](/docs/language-reference/) concepts that support modeling event-sourced systems and CQRS. +## Tutorial + +### Context and Objectives +This tutorial highlights the [Context Mapper DSL (CML)](/docs/language-reference/) concepts that support modeling event-sourced systems and CQRS. Within CML Bounded Contexts and Aggregates, we integrated the [Sculptor DSL for tactic DDD](http://sculptorgenerator.org/) that allows domain-driven designers to specify the domain model of Bounded Contexts. @@ -152,6 +154,6 @@ However, the DSL syntax itself does not need additional concepts to support it. ## Other Tutorials and Links * Tutorial: [Document Event Storming Results with Context Mapper](/docs/event-storming/) - * Presentation on Context Mapper:[Context Mapper: DSL and Tools for Domain-Driven Service Design - Bounded Context Modeling and Microservice Decomposition](https://contextmapper.org/media/ZIOSK-ContextMapper4JUGv10p.pdf) + * Presentation on Context Mapper: [Context Mapper: DSL and Tools for Domain-Driven Service Design - Bounded Context Modeling and Microservice Decomposition](https://contextmapper.org/media/ZIOSK-ContextMapper4JUGv10p.pdf) * Paper introducing the Context Mapper DSL (CML): [Domain-specific Language and Tools for Strategic Domain-driven Design, Context Mapping and Bounded Context Modeling](https://doi.org/10.5220/0008910502990306) From 93f06fae96ff0dcd4c5b9ee108941f7ad2242e0f Mon Sep 17 00:00:00 2001 From: Zimmermann Olaf Date: Mon, 23 Mar 2020 14:30:43 +0100 Subject: [PATCH 3/9] Pages on top-level docs folder --- _docs/examples.md | 12 ++-- _docs/faqs.md | 67 +++++++++---------- _docs/getting-started-create-project.md | 28 +++----- _docs/getting-started.md | 41 ++++++------ _docs/index.md | 24 +++---- .../reverse-engineering.md | 2 +- _docs/standalone-usage.md | 19 ++---- 7 files changed, 86 insertions(+), 107 deletions(-) diff --git a/_docs/examples.md b/_docs/examples.md index 6067b50..1860e31 100644 --- a/_docs/examples.md +++ b/_docs/examples.md @@ -3,9 +3,11 @@ title: Examples permalink: /docs/examples/ --- -Please find our CML examples in the following Github repository: [https://github.com/ContextMapper/context-mapper-examples](https://github.com/ContextMapper/context-mapper-examples). +Please find the CML examples featured on this page in the following GitHub repository: [https://github.com/ContextMapper/context-mapper-examples](https://github.com/ContextMapper/context-mapper-examples). -There you find an example of a fictitious insurance company and the DDD sample. All the graphical illustrations of our sample Context Maps are inspired by [Vernon][1] and [Brandolini][2]. +In the examples repository, you can find the domain model and strategic DDD description of the services and application landscape in Lakeside Mutual, a fictitious insurance company, and the CML version of a classical DDD sample (cargo routing and tracking). + +The following graphical illustrations of our sample Context Maps are inspired by [Vernon][1] and [Brandolini][2]. ## Insurance Example Link: [https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example) @@ -18,11 +20,9 @@ Link: [https://github.com/ContextMapper/context-mapper-examples/tree/master/src/ DDD Sample Context Map ## Architectural Refactoring (AR) Examples -The examples which you can find behind the link below provide smaller CML snippets of the insurance example to illustrate how -you can apply refactorings to your models. +The following folder contains a number of small CML snippets from the insurance example; they illustrate how you can apply refactorings to your models: -Link: [https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/architectural-refactorings](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/architectural-refactorings) +* [https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/architectural-refactorings](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/architectural-refactorings) [1]: https://www.amazon.de/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577 [2]: https://www.infoq.com/articles/ddd-contextmapping - diff --git a/_docs/faqs.md b/_docs/faqs.md index 9a1ea60..2ee6218 100644 --- a/_docs/faqs.md +++ b/_docs/faqs.md @@ -1,66 +1,59 @@ --- -title: FAQs +title: "Frequently Asked Questions (FAQs)" permalink: /docs/faq/ --- -Frequently asked questions: + ### Where can I download the Eclipse Plugin? Open the [Eclipse Marketplace](https://marketplace.eclipse.org/content/context-mapper) in Eclipse, search for "Context Mapper", and press "Install". -Alternatively, use the following Eclipse update site and install the plugin in Eclipse via *Help -> Install New Software...* (copy past the update site link) +Alternatively, use the following Eclipse Update site and install the plugin in Eclipse via *Help -> Install New Software...* (copy past the update site link). Update Site: [https://dl.bintray.com/contextmapper/context-mapping-dsl/updates/](https://dl.bintray.com/contextmapper/context-mapping-dsl/updates/) ### How do I create an Eclipse project with a new CML model to start modeling my Context Map? -Consult the page [Create CML Model](/docs/getting-started-create-project/) which describes how you setup your project to get started with modeling CML -Context Maps. +Consult the page [Create CML Model](/docs/getting-started-create-project/). It describes how to setup your project to get started with modeling CML Context Maps. ### How do I create a new context map? -Just create a file with the file extension **cml** (Context Mapping Language). Take a look at our example to get an idea how it looks like: [https://github.com/ContextMapper/context-mapper-examples](https://github.com/ContextMapper/context-mapper-examples) +Just create a file with the file extension **.cml** (Context Mapping Language). Take a look at our example to get an idea how the file content should look like: [https://github.com/ContextMapper/context-mapper-examples](https://github.com/ContextMapper/context-mapper-examples). Let the code completion and other editor features in Eclipse guide you while completing the map and modeling Bounded Contexts. ### Which DDD Patterns are supported by CML? Have a look at our [CML Reference - Introduction](/docs/language-reference/) page. You will find all patterns supported by CML there. ### Which combinations of Strategic DDD Patterns are allowed? -Have a look at the page [Language Semantic Model](/docs/language-model/) which introduces the semantic model of our DSL and lists the implemented semantic checkers. - -### Which transformations can I apply to my CML model? -Currently you can generate [MDSL](https://socadk.github.io/MDSL/) (micro-)service contracts providing assistance regarding how your -system can be implemented in an (micro-)service-oriented architecture, [Service Cutter](http://servicecutter.github.io/) input -to get suggestions for service cuts or new bounded context, and you can generate UML ([PlantUML](http://plantuml.com/)) diagrams -out of your CML. The following pages explain the generators in detail: - - * [Generate Graphical Context Maps](/docs/context-map-generator/) - * [Generate PlantUML Diagrams](/docs/plant-uml/) - * [Generate MDSL (Micro-)Service Contracts](/docs/mdsl/) - * [Generate Service Cutter Input Files](/docs/service-cutter/) - * [Generate Arbitrary Text Files](/docs/generic-freemarker-generator/) (with Freemarker templates) - -### How can I refactor my CML model? -The Context Mapper tool provides a set of architectural refactorings which you can apply to your model. Find more information and all -available refactorings [here](/docs/architectural-refactorings). +Have a look at the page [Language Semantic Model](/docs/language-model/). It introduces the semantic model of our DSL and lists the implemented semantic checkers. ### Where do I find a documentation regarding the tactic DDD syntax to specify a bounded context in detail? -The tactic DDD part of our DSL is based on the [Sculptor DSL](http://sculptorgenerator.org/). However, you can find a short introduction -and examples how you can detail your bounded contexts on the pages [Aggregate](/docs/aggregate/) and [Tactic DDD Syntax](/docs/tactic-ddd/). -If you are interested in more details and all features, we refer to the [Sculptor documentation](http://sculptorgenerator.org/documentation/advanced-tutorial). - -### I have other questions not listed here. How can I contribute? -If you have any questions not answered by our documentation page, we are happy if you create an issue in our documentation [repo](https://github.com/ContextMapper/contextmapper.github.io/issues). Of course, PR's are always welcome as well. - -Your [contribution](/getting-involved/) is welcome! +The tactic DDD part of our DSL is based on the [Sculptor DSL](http://sculptorgenerator.org/). We provide a short introduction and examples how you can detail your bounded contexts on the pages [Aggregate](/docs/aggregate/) and [Tactic DDD Syntax](/docs/tactic-ddd/). If you are interested in more details and all features, we refer to the [Sculptor documentation](http://sculptorgenerator.org/documentation/advanced-tutorial). ### How do I validate all CML models (*.cml files) in my Eclipse project? The CML models are validated when you save the *.cml automatically, if _"Build Automatically"_ is enabled in the _Project_ menu. -If it is not enabled you can validate all models by triggering _"Build All"_ in the _Project_ menu. +If it is not enabled, you can validate all models by triggering _"Build All"_ in the _Project_ menu. + +### Which transformations can I apply to my CML model? Which generators are available? +Currently you can generate [Microservice Domain-Soecific Language (MDSL)](https://socadk.github.io/MDSL/) (micro-)service contracts providing assistance regarding how your system can be implemented in an (micro-)service-oriented architecture, [Service Cutter](http://servicecutter.github.io/) input to get suggestions for service cuts or new bounded context, and you can generate UML ([PlantUML](http://plantuml.com/)) diagrams out of your CML. The following pages explain the generators in detail: + + * [Generate graphical Context Maps](/docs/context-map-generator/) + * [Generate PlantUML diagrams](/docs/plant-uml/) + * [Generate MDSL (micro-)service contracts](/docs/mdsl/) + * [Generate Service Cutter input files](/docs/service-cutter/) + * [Generate arbitrary text files](/docs/generic-freemarker-generator/) (with Freemarker templates) + +### How can I refactor my CML model? +The Context Mapper tool provides a set of [architectural refactorings](https://stefan.kapferer.ch/2019/09/05/service-decomposition-as-a-series-of-architectural-refactorings/) which you can apply to your model. Find more information and all +available refactorings [here](/docs/architectural-refactorings). ### Does Context Mapper support Event Sourcing and CQRS? -The concepts behind event sourcing and CQRS do not require special modeling objects other than _DomainEvents_, which are supported by the Context Mapper DSL (CML). The syntax to specify -the domain models within Bounded Contexts is based on [Sculptor](http://sculptorgenerator.org/) which supports event-driven concepts. Have a look at our -[Event Sourcing and CQRS Modeling in Context Mapper](/docs/event-sourcing-and-cqrs-modeling/) page to learn how to model events in CML. +The concepts behind event sourcing and CQRS do not require special modeling objects other than _DomainEvents_, which are supported by the Context Mapper DSL (CML). The syntax to specify the domain models within Bounded Contexts is based on [Sculptor](http://sculptorgenerator.org/) which supports event-driven concepts. +Have a look at our [Event Sourcing and CQRS Modeling in Context Mapper](/docs/event-sourcing-and-cqrs-modeling/) tutorial to learn how to model events in CML. ### Can I use Context Mapper to document Event Stormings? -Yes, the results of an Event Storming are based on the DDD concepts that are supported by Context Mapper. Have a look at our -[Model Event Storming Results in Context Mapper](/docs/event-storming/) tutorial that illustrates how Context Mapper can be used to +Yes, the results of an Event Storming are based on the DDD concepts that are supported by Context Mapper. Our +[Model Event Storming Results in Context Mapper](/docs/event-storming/) tutorial explains how Context Mapper can be used to document an Event Storming. + +### I have other questions not listed here. How can I contribute? +If you have any questions not answered by our documentation page, we appreciate if you create an issue in our documentation [repo](https://github.com/ContextMapper/contextmapper.github.io/issues). Of course, Pull Requests (PRs) are always welcome too. + +Active [contributions](/getting-involved/) are welcome as well! \ No newline at end of file diff --git a/_docs/getting-started-create-project.md b/_docs/getting-started-create-project.md index e35321a..5269aa0 100644 --- a/_docs/getting-started-create-project.md +++ b/_docs/getting-started-create-project.md @@ -3,8 +3,7 @@ title: Create CML Project permalink: /docs/getting-started-create-project/ --- -This page describes how you can start with Context Mapper and create your first CML model. Getting started with Context Mapper is easy and -includes the following first steps: +This page describes how you can start with Context Mapper and create your first CML model. Getting started with Context Mapper is easy, the following four steps will do: 1. Install Context Mapper plugin 2. Create an Eclipse project @@ -21,7 +20,7 @@ The Context Mapper Eclipse plugin can be installed via the marketplace: Drag to your running Eclipse* workspace. *Requires Eclipse Marketplace Client -Alternatively you can follow this procedure to install the plugin with our update site URL directly: +Alternatively, you can follow this procedure to install the plugin from update site URL directly: 1. Open the plugin installation dialog in Eclipse with the menu entry _Help -> Install New Software..._ 2. Enter the following update site URL to the field _Work with:_ on the top of the dialog: @@ -31,44 +30,39 @@ Alternatively you can follow this procedure to install the plugin with our updat ## 2. Create an Eclipse Project In order to create a CML model, you need an Eclipse project. You can use any project type such as _Java Project_, _Maven Project_, -_Gradle Project_ or just a general _Project_. Use the _File -> New_ menu or the context menu in the project explorer to create a project. +_Gradle Project_ or just a general _Project_. Use the _File -> New_ menu or the context menu in the Project Explorer to create a project. -**Note:** You can also use one of your existing projects and create a CML model there. In this case go to the next step. +**Note:** You can also use one of your existing projects and create a CML model there. In this case, skip this and continue with the next step. ## 3. Enable the Xtext Project Nature -As mentioned above, it does not matter which project type you use. However, your project has to be an Xtext project which means it needs -the Xtext nature. There are **two** easy **possibilities** to enable the Xtext nature on your project: +As mentioned above, it does not matter which project type you use. However, your project has to be an Xtext project, which means it requires the Xtext *nature* in Eclipse. There are ways to achieve this: * **Option 1**: Open the context menu on your project (right-click) and use the menu entry _Configure -> Convert to Xtext Project_. ![Enable Xtext nature on Eclipse project](/img/convert-to-xtext-project.png) * **Option 2**: Just jump to step four and create a file with the extension **.cml**. Eclipse will ask you if you want to enable the Xtext nature. Press _Yes_. ## 4. Create .cml Model File -Once you created your project, you can create a file with the extension **.cml** in order to start modeling with Context Mapper. Use the -_New Context Mapper DSL (CML) File_ wizard: +Once you have created your project, you can create a file with the extension **.cml** in order to start modeling with Context Mapper. Use the _New Context Mapper DSL (CML) File_ wizard: ![Create CML file wizard (1)](/img/screenshot-new-cml-file-1.png) ![Create CML file wizard (2)](/img/screenshot-new-cml-file-2.png) -**Note**: If you already enabled the Xtext nature in step three, the file opens and you can start modeling. Otherwise Eclipse will ask you now if you -want to enable it: +**Note**: If you already enabled the Xtext nature in step three, the file opens and you can start modeling. Otherwise Eclipse will ask you whether you want to enable it now: ![Enable Xtext nature at CML file creation](/img/create-cml-file-enable-nature.png) In this case you have to confirm with _Yes_. ## Ready to Model -You can now start with writing CML in the Context Mapper editor. Use the following resources to get started: +You can now start writing CML in the Context Mapper editor. Use the following resources to get started: * Introductory CML snippets on our [welcome page](/docs/home/) - * Example models in our [examples repository](https://github.com/ContextMapper/context-mapper-examples) + * Sample models in our [examples repository](https://github.com/ContextMapper/context-mapper-examples) * Detailed documentation about the language features in our [language reference](/docs/language-reference/) section. * [FAQ's](/docs/faq/) -If you want to model across multiple *.cml files, for example to use Bounded Contexts in multiple Context Maps, consult the [Imports](/docs/imports/) page of -our language reference. +*Note:* If you want to model across multiple *.cml files, for example to use Bounded Contexts in multiple Context Maps, consult the [Imports](/docs/imports/) page of our language reference. -Once you have modeled your system with CML you may want use our generators to produce other representations or evolve the model by using -out Architectural Refactorings (ARs): +Once you have modeled your system with CML, you may want use our generators to produce other representations or evolve the model by using [*Architectural Refactorings (ARs)*](https://www.infoq.com/articles/architectural-refactoring/): * [Architectural Refactorings (ARs)](/docs/architectural-refactorings/) * User Guides for generators: diff --git a/_docs/getting-started.md b/_docs/getting-started.md index 272be3b..d449e3a 100644 --- a/_docs/getting-started.md +++ b/_docs/getting-started.md @@ -3,46 +3,39 @@ title: Getting started permalink: /docs/getting-started/ --- -To model with Context Mapper you need our Eclipse Plugin providing the CML language and its surrounding tools. The integration of CML into other IDEs -will be released in the future but is not ready yet. +To model with Context Mapper you need our Eclipse Plugin providing the CML language and its surrounding tools. The integration of CML into other IDEs will be considered for future releases, but is not ready yet ([help wanted](/docs/getting-involved/)!). ## Install Context Mapper Eclipse Plugin -To start with Context Mapper install our Eclipse plugin via the **Eclipse Marketplace** or by using our **update site**: +To start using Context Mapper, please install the Eclipse plugin via the **Eclipse Marketplace** or our **update site**: **Eclipse Marketplace: [https://marketplace.eclipse.org/content/context-mapper/](https://marketplace.eclipse.org/content/context-mapper/)** **Update Site: [https://dl.bintray.com/contextmapper/context-mapping-dsl/updates/](https://dl.bintray.com/contextmapper/context-mapping-dsl/updates/)** ### System Requirements -To use the ContextMapper DSL Eclipse plugin you need the following tools: +To use the ContextMapper DSL Eclipse plugin, the following tools are required: * [Java JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) (JDK 8 or newer) * [Eclipse](https://www.eclipse.org/downloads/packages/) * ContextMapper Eclipse Plugin * Eclipse Marketplace: [https://marketplace.eclipse.org/content/context-mapper/](https://marketplace.eclipse.org/content/context-mapper/) * Eclipse Update Site: [https://dl.bintray.com/contextmapper/context-mapping-dsl/updates/](https://dl.bintray.com/contextmapper/context-mapping-dsl/updates/) -* If you want to use our [Context Map generator](/docs/context-map-generator/) you need to have [Graphviz](https://www.graphviz.org/) installed on your system. +* If you want to use our [Context Map generator](/docs/context-map-generator/), you must have installed [Graphviz](https://www.graphviz.org/) on your system. * Ensure that the binaries are part of the _PATH_ environment variable and can be called from the terminal. * Especially on Windows this is not the case after the installation of [Graphviz](https://www.graphviz.org/). The default installation path is `C:\Program Files (x86)\GraphvizX.XX`, which means you have to add `C:\Program Files (x86)\GraphvizX.XX\bin` to your _PATH_ variable. * You may want to install one the following two plugins to display the plantUML diagrams directly in Eclipse: * [Asciidoctor Editor](https://marketplace.eclipse.org/content/asciidoctor-editor) (Update site: [https://dl.bintray.com/de-jcup/asciidoctoreditor](https://dl.bintray.com/de-jcup/asciidoctoreditor)) * [PlantUML Eclipse Plugin](https://github.com/hallvard/plantuml) (Update site: [http://hallvard.github.io/plantuml/](http://hallvard.github.io/plantuml/)) - * **Note:** Both plugins require [Graphviz](http://www.graphviz.org/) to be installed on your machine! - * Alternatively you can use the [plantUML online server](http://www.plantuml.com/plantuml/uml). + * **Note:** Both plugins also require [Graphviz](http://www.graphviz.org/) to be installed on your machine! + * Alternatively you can use a [plantUML online server](http://www.plantuml.com/plantuml/uml). **Note**: If you want to integrate the DSL and its tools as library within your application, find more information [here](/docs/library/). ### Latest Releases Release notes for all our latest releases can be found [here](https://github.com/ContextMapper/context-mapper-dsl/releases). -## Next steps ... -After you installed the Context Mapper Eclipse plugin you can create a CML (Xtext) project and start modeling. Find more information how to create -such a project here: - * [Create CML Project](/docs/getting-started-create-project/) - -Check out our **[example models](/docs/examples/)** and the [language reference](/docs/language-reference/) to create your first CML models. - +## Example The following example gives you a first impression how CML context maps look like: ([DDD Sample Application](https://github.com/citerus/dddsample-core)) 
/** 
@@ -63,8 +56,10 @@ The following example gives you a first impression how CML context maps look lik
 }
+ + The bounded contexts have to be specified before you can use them within a context map. -A simple example of a bounded context definition: +A simple example of a bounded context definition is: 
BoundedContext LocationContext {
   Module location {
@@ -90,7 +85,16 @@ A simple example of a bounded context definition:
 }
-## Refactorings and Generators +## Next steps... + + +### A First Model +Once you have installed the Context Mapper Eclipse plugin, you can create a CML (Xtext) project and start modeling. Find more information how to create such a project here: + * [Create CML Project](/docs/getting-started-create-project/) + +Check out our [example models](/docs/examples/) and the [language reference](/docs/language-reference/) if you do not want to start with an empty CML model. + +### Refactorings and Generators Once you created your first Context Map in CML you can use the following tools to evolve your model and generate other representations of your architecture: * Use [Architectural Refactorings (ARs)](/docs/architectural-refactorings/) to evolve your model iteratively. @@ -101,7 +105,6 @@ Once you created your first Context Map in CML you can use the following tools t * Generate [Service Cutter](/docs/service-cutter/) input files * Generate [arbitrary textual files with Freemarker templates](/docs/generic-freemarker-generator/) -## Reverse Engineer Context Map and Bounded Contexts -In case you work on a project with existing monolithic or (micro-)service-oriented architectures you may want to reverse engineer an initial Context Map -or the domain models within your Bounded Contexts to simplify the start with our tool. In this case have a look at our [reverse engineering library](/docs/reverse-engineering) +### Reverse Engineer Context Map and Bounded Contexts +In case you work on a project with existing monolithic or (micro-)service-oriented architectures you may want to reverse engineer an initial Context Map or the domain models within your Bounded Contexts to simplify the start with our tool. In this case have a look at our [reverse engineering library](/docs/reverse-engineering) which is able to generate CML models from existing source code. diff --git a/_docs/index.md b/_docs/index.md index 4f526c6..2a933b2 100644 --- a/_docs/index.md +++ b/_docs/index.md @@ -4,9 +4,8 @@ permalink: /docs/home/ redirect_from: /docs/index.html --- -Context Mapper is a modular and extensible modeling framework based on **Domain-driven Design (DDD)** and its strategic patterns. -The **[core component](/docs/language-reference/)** provides a DSL to create context maps based on these DDD patterns. The model behind the language and its semantic rules aim -to formalize **our interpretation of the DDD patterns** and how they can be combined in a concise manner. +Context Mapper is a modular and extensible modeling framework for **Domain-driven Design (DDD)** and its strategic patterns. +The **[core component](/docs/language-reference/)** provides a DSL to create context maps featuring these DDD patterns. The model behind the language and its semantic rules express **our interpretation of the DDD patterns** and how these patterns can be combined in a concise and consistent manner. At present, Context Mappers comes as an Eclipse plugin (with a standalone Java [library version](/docs/library/) also being available): **Eclipse Marketplace: [https://marketplace.eclipse.org/content/context-mapper/](https://marketplace.eclipse.org/content/context-mapper/)** @@ -16,21 +15,16 @@ to formalize **our interpretation of the DDD patterns** and how they can be comb ![Context Mapper Framework Components](/img/context-mapper-framework-components.png) -DDD and its bounded contexts further provide an approach for **decomposing a domain** into multiple -bounded contexts. With our **[Service Cutter](/docs/service-cutter-context-map-suggestions/)** integration (proof-of-concept) we illustrate how -the Context Mapper DSL (CML) can be used as a foundation for structured service decomposition approaches. Based on its [coupling criteria](https://github.com/ServiceCutter/ServiceCutter/wiki/Coupling-Criteria) -the Context Mapper tool suggests new Context Maps which may improve the architecture with respect to coupling and cohesion. -The **[Architectural Refactorings (ARs)](/docs/architectural-refactorings)** support to decompose a Context Map in an iterative manner. +DDD and its Bounded Contexts provide an approach for **decomposing a domain**. With our **[Service Cutter](/docs/service-cutter-context-map-suggestions/)** integration (currently in proof-of-concept state) we illustrate how the Context Mapper DSL (CML) can be used as a foundation for even more structured service decomposition approaches. Based on its [coupling criteria](https://github.com/ServiceCutter/ServiceCutter/wiki/Coupling-Criteria), Context Mapper suggests new Context Maps which may improve the architecture with respect to coupling and cohesion. **[Architectural Refactorings (ARs)](/docs/architectural-refactorings)** support to decompose a Context Map in an iterative manner. -If you work on a project with an existing monolithic or (micro-)service-oriented architecture, you can initially use our -**[reverse engineering library](/docs/reverse-engineering)** to generate a CML context map out of existing code. The library is built in an extensible fashion -and allows to implement different bounded context and context map discovery strategies. +If you work on a project with an existing monolithic or (micro-)service-oriented architecture, you can use our +**[reverse engineering library](/docs/reverse-engineering)** to recreate a CML context map from the existing code ([architecture recovery](https://en.wikipedia.org/wiki/Software_architecture_recovery)). This library is built in an extensible fashion, allowing the implementation different bounded context and context map discovery strategies. At present, Spring Boot applications and Docker compose files can be analyzed by existing strategies. -The provided **[generators](/docs/generators)** allow to transform the CML context maps into other representations of the architectural model. We currently -offer the following generators: - * Graphical Context Map [generator](/docs/context-map-generator/) +The provided model transformations and **[generators](/docs/generators)** allow transforming the CML context maps into other representations of the architectural model. We currently offer the following generators: + + * Graphical Context Map [generator](/docs/context-map-generator/) based on Graphviz (supported formats: .png, .cvg., .dot), * [PlantUML](http://plantuml.com/) component and class diagram [generator](/docs/plant-uml/) - * [MDSL](https://socadk.github.io/MDSL/) (micro-)service contracts [generator](/docs/mdsl/) + * [Microservice Domain-Speciifc Language (MDSL)](https://socadk.github.io/MDSL/) (micro-)service contracts [generator](/docs/mdsl/) * [Service Cutter](http://servicecutter.github.io/) input files [generators](/docs/service-cutter/) * [Generic Textual Generator based on Freemarker Templates](/docs/generic-freemarker-generator/) diff --git a/_docs/reverse-engineering/reverse-engineering.md b/_docs/reverse-engineering/reverse-engineering.md index a17414c..b97c50a 100644 --- a/_docs/reverse-engineering/reverse-engineering.md +++ b/_docs/reverse-engineering/reverse-engineering.md @@ -70,7 +70,7 @@ public class LakesideMutualContextMapDiscoverer { The library is based on strategies implementing the three interfaces `BoundedContextDiscoveryStrategy`, `RelationshipDiscoveryStrategy`, and `BoundedContextNameMappingStrategy`. The `BoundedContextNameMappingStrategy` strategy can be used to map different bounded context names between the bounded context and relationship strategies. In this example we use the `SpringBootBoundedContextDiscoveryStrategy` to discover the bounded contexts via Spring annotations. It -derives [Bounded Contexts](https://github.com/ContextMapper/language-reference/bounded_context) from applications, [Aggregates]((../language-reference/aggregate)) from REST endpoints, and Entities from the REST endpoint methods. The `DockerComposeRelationshipDiscoveryStrategy` strategy is used to derive the relationships between the bounded context from the `docker-compose.yml` file. The extended `SeparatorToCamelCaseBoundedContextNameMappingStrategy` in the example above is used to map names such as 'customer-management-backend' (name according to relationship strategy) to 'CustomerManagement' (name according the discovered bounded context). +derives [Bounded Contexts](/docs/language-reference/bounded_context) from applications, [Aggregates]((/docs/language-reference/aggregate)) from REST endpoints, and Entities from the REST endpoint methods. The `DockerComposeRelationshipDiscoveryStrategy` strategy is used to derive the relationships between the bounded context from the `docker-compose.yml` file. The extended `SeparatorToCamelCaseBoundedContextNameMappingStrategy` in the example above is used to map names such as 'customer-management-backend' (name according to relationship strategy) to 'CustomerManagement' (name according the discovered bounded context). The code above creates the following context map for the application: diff --git a/_docs/standalone-usage.md b/_docs/standalone-usage.md index 08e55a4..0c85728 100644 --- a/_docs/standalone-usage.md +++ b/_docs/standalone-usage.md @@ -3,15 +3,11 @@ title: Usage as Library permalink: /docs/library/ --- -Besides using the Context Mapper DSL (CML) and its tools within our Eclipse plugin, it can also be integrated into other applications as a -library. The library allows to parse CML files within a project, change the model programmatically and unparse it back to CML, and use our -tools such as the [Architectural Refactorings](/docs/architectural-refactorings/) and the provided generators -([PlantUML](/docs/plant-uml/), [MDSL](/docs/mdsl/), [Service Cutter](/docs/service-cutter/)). +The Context Mapper DSL (CML) and its tools cannot only be used within Eclipse, but also be integrated into other applications as a +standalone library. This library allows you to parse CML files within a project, change the model programmatically, and unparse it back to CML. You can also use tools such as the [Architectural Refactorings](/docs/architectural-refactorings/) and the provided generators for [graphical context maps](/docs/context-map-generator/), [PlantUML](/docs/plant-uml/), [MDSL](/docs/mdsl/), [Service Cutter](/docs/service-cutter/), and [Freemarker templates](/docs/generic-freemarker-generator/). ## Integration -All our releases are not only published as Eclipse Plugin but as standalone library as well. The library is published into the [Maven -central repository](https://search.maven.org/artifact/org.contextmapper/context-mapper-dsl/) and can easily be integrated into your Maven -or Gradle build: +All our releases are not only published as Eclipse Plugins, but as updates to the standalone library as well. The library is published into the [Maven central repository](https://search.maven.org/artifact/org.contextmapper/context-mapper-dsl/) and can easily be integrated into your Maven or Gradle build: **Gradle**: ```gradle @@ -27,15 +23,14 @@ implementation 'org.contextmapper:context-mapper-dsl:{our-latest-version}' ``` -Latest release: [![Maven Central](https://img.shields.io/maven-central/v/org.contextmapper/context-mapper-dsl.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22org.contextmapper%22%20AND%20a:%22context-mapper-dsl%22) +The latest release can be fund here: [![Maven Central](https://img.shields.io/maven-central/v/org.contextmapper/context-mapper-dsl.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22org.contextmapper%22%20AND%20a:%22context-mapper-dsl%22) ## Example Project -If you want to use Context Mapper as library within your application, have a look at our standalone example project here: +If you want to use Context Mapper as library within your application, have a look at our standalone example project: [https://github.com/ContextMapper/context-mapper-standalone-example](https://github.com/ContextMapper/context-mapper-standalone-example) -It illustrates how you can setup your project (with Gradle) so that your CML files are compiled at build-time as well. It further provides -code examples in Java how you can use the models within your project (parse, unparse, use generators). +This project illustrates how to setup your project (with Gradle) so that your CML files are compiled at build-time as well. It further provides code examples in Java that show how to use the models within your project (for example: parse, unparse, and use generators). -If you have further questions regarding the library usage of Context Mapper +If you have further questions regarding the library usage of Context Mapper, please [create an issue in our Github repository](https://github.com/ContextMapper/context-mapper-dsl/issues) or feel free to [get in touch with us](/getting-involved/#get-in-touch-with-us). From 2f1d410bba555c5f8f6cf870856652352dd5af0c Mon Sep 17 00:00:00 2001 From: Zimmermann Olaf Date: Mon, 23 Mar 2020 15:38:01 +0100 Subject: [PATCH 4/9] CM, BC, Aggregate pages --- _docs/language-reference/aggregate.md | 33 +++++------ _docs/language-reference/bounded-context.md | 33 +++++------ _docs/language-reference/context-map.md | 55 ++++++++----------- _docs/language-reference/language-model.md | 9 ++- .../language-reference/language-reference.md | 36 ++++++------ 5 files changed, 80 insertions(+), 86 deletions(-) diff --git a/_docs/language-reference/aggregate.md b/_docs/language-reference/aggregate.md index 0402360..3b5fb60 100644 --- a/_docs/language-reference/aggregate.md +++ b/_docs/language-reference/aggregate.md @@ -4,14 +4,16 @@ permalink: /docs/aggregate/ --- The Aggregate pattern implementation from [Sculptor](http://sculptorgenerator.org/) has been adapted within CML to represent it with a -separate grammar rule. For a short introduction to the syntax of the other tactic DDD patterns, please have a look at [Tactic DDD Syntax](/docs/tactic-ddd/). +separate grammar rule. + +For a short introduction to the syntax of the other tactic DDD patterns, please have a look at [Tactic DDD Syntax](/docs/tactic-ddd/). For more details, we refer to the [Sculptor project](http://sculptorgenerator.org/) and its [documentation](http://sculptorgenerator.org/documentation/advanced-tutorial). ## Syntax -The aggregate supports the [Responsibility Layers](/docs/responsibility-layers/) pattern and the [Knowledge Level](/docs/knowledge-level) pattern. -An aggregate can further contain Services, Resources, Consumers and SimpleDomainObjects (Entities, Value Objects, Domain Events, etc.) -which are not further introduced here. The according rules are defined by the [Sculptor DSL](http://sculptorgenerator.org/), as already mentioned. -However, the following CML snippet illustrates an example of an aggregate to provide an impression how the rule can be used. +The aggregate supports the [Responsibility Layers](/docs/responsibility-layers/) pattern and the [Knowledge Level](/docs/knowledge-level) pattern. An aggregate can further contain Services, Resources, Consumers and SimpleDomainObjects (Entities, Value Objects, Domain Events, etc.) which are not further introduced here. +The respective rules are defined by the [Sculptor DSL](http://sculptorgenerator.org/), as already mentioned. + +The following CML snippet illustrates an example of an aggregate to provide an impression how the rule can be used: 
Aggregate Contract {
   responsibilities = "Contracts", "Policies"
@@ -36,16 +38,16 @@ However, the following CML snippet illustrates an example of an aggregate to pro
   }
 }
-The equal sign (=) to assign an attribute value is always optional and can be omitted. +The equal sign (=) to assign an attribute value is always optional and therefore can be omitted.
Note: Aggregate names must be unique within the whole CML model.
-Further examples can be found within our Github example repository [context-mapper-examples](https://github.com/ContextMapper/context-mapper-examples). +Further examples can be found within our GitHub example repository [context-mapper-examples](https://github.com/ContextMapper/context-mapper-examples). ## Aggregate Owner -CML allows to specify an owner on aggregate level. If aggregates are maintained by different teams, you can specify this as in the +CML allows specifying an owner on the aggregate level. If aggregates are maintained by different teams, you can specify this as in the following example: 
BoundedContext CustomerSelfServiceContext implements CustomerManagementDomain {
@@ -77,10 +79,10 @@ following example:
 }
-This may be used for service decomposition by using the [Split Bounded Context by Owners](/docs/ar-split-bounded-context-by-owners) +The _owner_ attribute may be used for service decomposition by using the [Split Bounded Context by Owners](/docs/ar-split-bounded-context-by-owners) architectural refactoring. -Note that the _owner_ attribute refers to a team, which is a bounded context of the type _TEAM_: (see [Bounded Context](/docs/bounded-context) for more details) +Note that the _owner_ attribute refers to a team, which must be a bounded context of the type _TEAM_: (see [Bounded Context](/docs/bounded-context) for more details): 
/* Team Definitions */
 BoundedContext CustomerBackendTeam {
@@ -93,10 +95,9 @@ Note that the _owner_ attribute refers to a team, which is a bounded context of
## Aggregate Use Cases -With CML you can further specify by which use cases an aggregate is used. This may be used for service decomposition by using the -[Split Bounded Context by Use Cases](/docs/ar-split-bounded-context-by-use-cases) architectural refactoring. +With CML you can further specify which use cases work with an aggregate. This information may be used for service decomposition when applying the [Split Bounded Context by Use Cases](/docs/ar-split-bounded-context-by-use-cases) architectural refactoring. -Assigning aggregates to use cases can be done with the _useCases_ attribute as follows: +Aggregates are assigned to use cases with the _useCases_ attribute: 
BoundedContext PolicyManagementContext implements PolicyManagementDomain {
   Aggregate Offers {
@@ -165,8 +166,8 @@ You can also refer to multiple use cases by providing a comma-separated list:
 
 ### Use Case Declaration
 The use cases you refer to have to be declared on the root level of your CML file. To declare a use case, use the keyword _UseCase_.
-A use case can be declared by simply give the case a name, as shown in the example below. If you want to provide further information
-about the use case you can specify which attributes of which entities are read and written by this use case (strings only; no references): 
+A use case can be declared by simply giving it a name, as shown in the example below. If you want to provide further information
+about the use case, you can specify which attributes of which entities are read and written by this use case (strings only; no references): 
 
 
/* Simple use case (only name given) */
 UseCase UpdateContract
@@ -188,7 +189,7 @@ an aggregate is. The attribute takes one of the following three values:
  * OFTEN
  
 This attribute may be used for service decomposition, since parts which are likely to change should typically be isolated in separate
-components (see [Parnas](https://dl.acm.org/citation.cfm?doid=361598.361623)). In CML you can use this by applying the 
+components (see [Parnas](https://dl.acm.org/citation.cfm?doid=361598.361623)). You can use this in CML by applying the 
 [Extract Aggregates by Volatility](/docs/ar-extract-aggregates-by-volatility) architectural refactoring.
 
 The likelihood on an aggregate is declared as follows:
diff --git a/_docs/language-reference/bounded-context.md b/_docs/language-reference/bounded-context.md
index 0711dc3..15f55bc 100644
--- a/_docs/language-reference/bounded-context.md
+++ b/_docs/language-reference/bounded-context.md
@@ -3,8 +3,7 @@ title: Bounded Context
 permalink: /docs/bounded-context/
 ---
 
-Bounded contexts are defined on the root level of a CML (*.cml) file and then referenced on a context map which defines the relationships with other bounded contexts.
-Have a look at [context map](/docs/context-map/) to see how you add a bounded context to your context map. 
+Bounded contexts are defined on the root level of a CML (*.cml) file and then referenced on a context map which defines the relationships with other bounded contexts. Have a look at [context map](/docs/context-map/) to see how you add a bounded context to your context map. 
 
 ## Syntax
 The following example illustrates how a bounded context is defined in CML (syntactical features). The **Customer Management** context is a context within our fictitious insurance company example. The whole example with the context map and all bounded contexts can be found [here](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example).
@@ -40,28 +39,25 @@ The following example illustrates how a bounded context is defined in CML (synta
 Note: Bounded Context names must be unique within your CML model.
 

  
-With the **implements** keyword you specify which domain or subdomains are implemented by this bounded context. After the **implements**
-keyword you can either reference a list of subdomains (comma-separated) or one complete domain. See [Subdomain](/docs/subdomain/) to 
-learn how subdomains are specified.
+The **implements** keyword specifies which domain or subdomains are implemented by this bounded context. Behind the **implements**
+keyword you can either reference a list of subdomains (comma-separated) or one top-level domain. Consult [Subdomain](/docs/subdomain/) to  learn how subdomains are specified.
 
-The equal sign (=) to assign attribute values is optional and can be omitted. Attribute values are then assigned as follows:
+Attribute values are assigned as follows:
 
BoundedContext ContextMapperTool refines StrategicDomainDrivenDesignContext {
   type FEATURE
   domainVisionStatement "Context Mapper provides a formal way to model strategic DDD Context Maps."
   implementationTechnology "Java, Eclipse"
 }
 

+An equal sign (=) to assign attribute values may be present but can be omitted.
 
-The example above further shows how you can refine another bounded context with the **refines** keyword. This feature allows you to create
-some kind of an inheritance hierarchy in case one bounded context can be seen as a refinement of another bounded context. However, note
-that this is only a modeling information and generators do not recursively resolve the domain model (Aggregates, etc.) of refined 
-bounded contexts.
+The example above also shows how you can let one bounded context refine another one (with the **refines** keyword). This feature allows you to create some kind of an inheritance hierarchy in case one bounded context can be seen as a refinement of another bounded context. However, note that this is only a modeling information and generators do not recursively resolve the domain model (Aggregates, etc.) of refined bounded contexts.
  
   
 All of the following attributes are **optional** and you do not have to specify them all. 
  
 ### Bounded Context Type
-With the _type_ keyword you define the bounded contexts type, which can be one of the following:
+With the _type_ keyword you define the bounded contexts type, which can be one of the following: 
 
  * FEATURE
  * APPLICATION
@@ -69,17 +65,16 @@ With the _type_ keyword you define the bounded contexts type, which can be one o
  * TEAM
  
 The type provides an indicator for which reason a bounded context may have been evolved. It further allows you to specify from which 
-viewpoint you describe your bounded contexts. For example you may want to create a team map, within which every bounded context reflects 
-a team, inspired by [Brandolini](https://www.infoq.com/articles/ddd-contextmapping). A team map further allows you to specify which team 
-is implementing which bounded contexts. Note that the context map type must be ORGANIZATIONAL to specify a team map. The corresponding 
-syntax is described under [context map](/docs/context-map) and an example for a team map can be found 
+viewpoint you describe your bounded contexts. FEATURE contexts are analysis or early design abstractions, taking a functional scenario view. Application contexts represent more elaborated, logical designs and implementation views; system contexts add a more physical, process- and deployment-oriented view.   
+
+Finally, you may want to create a team map, within which every bounded context reflects a team, inspired by [Brandolini](https://www.infoq.com/articles/ddd-contextmapping). A team map further allows you to specify which team is implementing which bounded contexts (of type FEATURE, APPLICATION, or SYSTEM). Note that the context map type must be ORGANIZATIONAL to specify a team map. The corresponding syntax is described under [context map](/docs/context-map) and an example for a team map can be found 
 [here](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example).
 
 ### Domain Vision Statement
-With the _domainVisionStatement_ keyword you can describe the vision statement of your bounded context, according to the DDD Domain Vision Statment pattern.
+With the _domainVisionStatement_ keyword you can describe the vision statement of your bounded context, according to the DDD Domain Vision Statement pattern. See [this page](/docs/domain-vision-statement/).
 
 ### Implementation Technology
-The _implementationTechnology_ attribute allows you to add information about how the corresponding bounded context is implemented.
+The _implementationTechnology_ attribute allows you to add information about how the corresponding bounded context is implemented. Note that this attribute does not correspond to any DDD pattern.
 
 ### Responsibility Layers
 With the _responsibilities_ keyword you are allowed to specify the responsibilities of the bounded context, according to the DDD Responsibility Layers pattern. See [responsibility layers](/docs/responsibility-layers/).
@@ -89,7 +84,7 @@ With the _knowledgeLevel_ attribute you define the knowledge level of the bounde
  * CONCRETE
  * META
  
-This attribute allow you to define the knowledge level according to the DDD Knowledge Level pattern.
+This attribute allow you to define the knowledge level according to the DDD Knowledge Level pattern. See [this page](/docs/knowledge-level/).
 
 ### Team _realizes_ Bounded Context
 If your bounded context is of the type TEAM, you can specify which bounded context the team implements by using the _realizes_ keyword. The following example illustrates this:
@@ -102,7 +97,7 @@ If your bounded context is of the type TEAM, you can specify which bounded conte
 
 
 ## The Bounded Context Building Blocks
-Within a bounded context you can create _Modules_ and _Aggregates_, as illustrated in the example at the beginning of this page. On this tactical DDD level we integrated the [Sculptor DSL](http://sculptorgenerator.org/).
+Within a bounded context, you can create _Modules_ and _Aggregates_ as illustrated in the example at the beginning of this page. On this tactical DDD level we integrated the [Sculptor DSL](http://sculptorgenerator.org/).
 This means within a module and an aggregate you can use all the [Sculptor features](http://sculptorgenerator.org/documentation/advanced-tutorial) to specify your bounded context, such as Entities, Value Objects, Domain Events, Services, Repositories, etc.
 
 Use the [Sculptor Documentation](http://sculptorgenerator.org/documentation/advanced-tutorial) and our [examples](https://github.com/ContextMapper/context-mapper-examples) to find out how you specify your bounded context.
diff --git a/_docs/language-reference/context-map.md b/_docs/language-reference/context-map.md
index 109512d..e954ed1 100644
--- a/_docs/language-reference/context-map.md
+++ b/_docs/language-reference/context-map.md
@@ -35,17 +35,16 @@ Alternatively, you can use only one _contains_ keyword and list all bounded cont
 }
-As you can see in the example above, it is also possible to name a context map (optional). In addition, the equal sign (=) to assign an -attribute value as done in the first example is optional and can be omitted. +As you can see in the example above, it is also possible to name a context map (the name is optional). The equal sign (=) to assign an attribute value as done in the first example can be omitted as well. A context map can be of one of the following **types**: * SYSTEM_LANDSCAPE * ORGANIZATIONAL -While a SYSTEM_LANDSCAPE represents the typical context map with the relationships between bounded contexts, an ORGANIZATIONAL map (or 'team map') illustrates the relationships between teams. An example for such a team map can be found [here](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example). +A SYSTEM_LANDSCAPE represents the default type of context map in which the bounded contexts represent software systems (or applications). The second type, an ORGANIZATIONAL map (or 'team map'), illustrates the relationships between teams. An example for such a team map can be found [here](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example). -The **state** attribute accepts the following two values, expressing if the given context map represents the current or the desired state: +The **state** attribute accepts the following two values, expressing whether the given context map represents the current or a desired state (this distinction is often made in [enterprise architecture management](https://searcherp.techtarget.com/definition/enterprise-asset-management-EAM) and [portfolio- or program-level project planning](https://www.pmi.org/learning/library/integrated-portfolio-program-management-7409)): * AS_IS * TO_BE @@ -53,26 +52,25 @@ The **state** attribute accepts the following two values, expressing if the give ## Relationships According to our [semantic model](/docs/language-model/), we support the following symmetric relationships: -* Partnership -* Shared Kernel +* Partnership (P) +* Shared Kernel (SK) The asymmetric relationships are represented by the following two types: * Upstream-Downstream (generic) -* Customer-Supplier (a special form of an Upstream-Downstream relationship) +* Customer-Supplier (C/S), a special form of an Upstream-Downstream relationship
Note: A customer-supplier relationship is an upstream-downstream relationship where the downstream priorities factor into upstream planning. The upstream team may succeed interdependently of the fate of the downstream team and therefore the needs of the downstream have to be addressed by the upstream. They interact as customer and supplier. A generic upstream-downstream relationship is not necessarily a customer-supplier relationship! (in CML you have to express this -explicitely) +explicitly)

-The syntax for upstream-downstream relationships is explained below. For the syntax of customer-supplier relationships please -visit Customer/Supplier. +The syntax for upstream-downstream relationships is explained below. To learn about the syntax of customer-supplier relationships, please visit Customer/Supplier.
-For the symmetric relationships and their syntax please visit [Partnership](/docs/partnership/) and [Shared Kernel](/docs/shared-kernel/). +The symmetric relationships and their syntax are introduced on separate pages: [Partnership](/docs/partnership/) and [Shared Kernel](/docs/shared-kernel/). Upstream-Downstream relationships can be defined with three different syntax variants, all illustrated with the examples below: @@ -88,14 +86,13 @@ Upstream-Downstream relationships can be defined with three different syntax var 
CargoBookingContext Downstream-Upstream LocationContext
-All of the four variants are semantically equivalent. Note that the arrow _->_ always points from the upstream to the downstream and thus, expresses the influence flow (the upstream has an influence on the downstream, but the downstream has no influence on the upstream). +All of the four variants are semantically equivalent. Note that the arrow _->_ always points from the upstream to the downstream and thus expresses an *influence flow* (the upstream has an influence on the downstream, but the downstream has no influence on the upstream). -With a colon at the end, you can give every relationship a name: +A colon at the end assigns a relationship a name: 
CargoBookingContext [D]<-[U] LocationContext : CargoLocationRelationship
-**Note:** The following quick upstream/downstream syntax without brackets can be used as well. It denotes a common upstream/downstream relationship without any roles. -However, with this syntax it is maybe not explicitly clear for a reader that you declare an upstream/downstream and **not** a customer/supplier relationship. +**Note:** The following quick upstream/downstream syntax without brackets can be used as well. It denotes a common upstream/downstream relationship without any roles. However, with this syntax it is less clear for a reader that you declare an upstream/downstream and *not* a customer/supplier relationship. 
CargoBookingContext <- LocationContext
@@ -104,44 +101,42 @@ However, with this syntax it is maybe not explicitly clear for a reader that you ### Relationship Roles -Within the brackets you can further specify the relationship roles such as Open Host Service (OHS) or Anti-Corruption Layer (ACL). +You can further specify the relationship roles such as Open Host Service (OHS) or Anti-Corruption Layer (ACL) within the brackets. Roles must always be specified behind the **U** (upstream) and the **D** (downstream) if they are not omitted. 
VoyagePlanningContext [D,ACL]<-[U,OHS,PL] LocationContext
-Since the arrow already indicates which Bounded Context is upstream and which is downstream, it is also possible to add the relationship -roles within the brackets without the **U** and the **D**: +Since the arrow already indicates which Bounded Context is upstream and which is downstream, it is also possible to add the relationship roles within the brackets without the **U** and the **D**: 
VoyagePlanningContext [ACL]<-[OHS,PL] LocationContext
-If you use the _Upstream-Downstream_ or _Downstream-Upstream_ keywords the roles are declared equivalently, but without the **D** and **U**: -(note that it does not matter if you write a whitespace before or after the brackets, or both) +If you use the _Upstream-Downstream_ or _Downstream-Upstream_ keywords the roles are declared equivalently, but without the **D** and **U** (note that it does not matter if you write a whitespace before or after the brackets, or both): 
VoyagePlanningContext[ACL] Downstream-Upstream [OHS,PL]LocationContext
-Upstream roles are given by the [Open Host Service (OHS)](/docs/open-host-service/) and +Upstream roles are defined by the [Open Host Service (OHS)](/docs/open-host-service/) and [Published Language (PL)](/docs/published-language/) patterns. Downstream roles are [Conformist (CF)](/docs/conformist/) and [Anticorruption Layer (ACL)](/docs/anticorruption-layer/). ### Relationship Attributes -By using brackets {}, you can specify further attributes for a relationship. Currently supported attributes are: +By using brackets {}, you can specify additional attributes for a relationship: * implementationTechnology * downstreamRights * exposedAggregates #### Implementation Technology -Within the body of the declaration it is possible to specify the implementation technology used to realize this relationship: +Within the body of the declaration, it is possible to specify the implementation technology used to realize this relationship: 
VoyagePlanningContext [D,ACL]<-[U,OHS,PL] LocationContext {
     implementationTechnology = "RESTful HTTP"
 }
#### Downstream Governance Rights -With the attribute _downstreamRights_ you can define which governance rights, and therefore which influence, the downstream has on the upstream within the specified relationship: +The attribute _downstreamRights_ defines which governance rights, and therefore which influence, the downstream has on the upstream within the specified relationship: 
VoyagePlanningContext [D,ACL]<-[U,OHS,PL] LocationContext {
     implementationTechnology = "RESTful HTTP"
@@ -158,9 +153,7 @@ The possible governance rights values are:
 * MONOPOLIST
 
 #### Exposed Aggregates
-The _exposedAggregates_ attribute offers the possibility to declare which [Aggregates](/docs/aggregate) of the **upstream** bounded context are exposed
-in order to realize this relationship. The attribute takes a comma separated list of references to aggregates. The referenced aggregates must
-be part of the upstream context of the relationship.
+The _exposedAggregates_ attribute offers the possibility to declare which [Aggregates](/docs/aggregate) of the **upstream** bounded context are exposed in order to realize this relationship. The attribute takes a comma-separated list of references to Aggregates. The referenced Aggregates must be part of the upstream context of the relationship.
 
 
VoyagePlanningContext [D,ACL]<-[U,OHS,PL] LocationContext {
     implementationTechnology = "RESTful HTTP"
@@ -173,11 +166,11 @@ be part of the upstream context of the relationship.
 For the Customer-Supplier relationship, which is a special form of Upstream-Downstream relationship, please visit [Customer-Supplier](/docs/customer-supplier).
 
 ## Semantic Rules
-Note that semantic rules (validators) exist for context maps within CML. This means that not every combination of patterns and concepts is allowed, even if it would be syntactically correct.
+Note that semantic rules (validators) exist for context maps within CML. This means that not every combination of patterns and concepts is allowed (even if it was syntactically correct).
 The following rules apply to a context map:
 
-* A bounded context which is not part of the context map (referenced with the _contains_ keyword), can not be referenced from a relationship rule within that context map.
-* A bounded context of the type TEAM can not be contained in a context map if the context map type is SYSTEM_LANDSCAPE. 
-* If the context map type of a context map is ORGANIZATIONAL, every bounded context added to the context map (with the _contains_ keyword) has to be of the type TEAM.
+* A Bounded Context which is not part of the Context Map (referenced with the _contains_ keyword), can not be referenced from a relationship rule within that Context Map.
+* A Bounded Context of the type TEAM can not be contained in a Context Map of type SYSTEM_LANDSCAPE. 
+* If the type of a Context Map is ORGANIZATIONAL, every Bounded Context added to it (indicated by the keyword _contains_) has to be of the type TEAM.
  
 For a summary of all semantic rules and further justifications, please consult [Language Semantics](/docs/language-model/).
diff --git a/_docs/language-reference/language-model.md b/_docs/language-reference/language-model.md
index 4d06083..15f9421 100644
--- a/_docs/language-reference/language-model.md
+++ b/_docs/language-reference/language-model.md
@@ -7,13 +7,18 @@ The CML language is based on the following strategic DDD domain model (or semant
 
 CML Language Semantic Model
 
-All the knowledge regarding the DDD patterns is derived from Evan's DDD book and his DDD reference:
+The language representation of the DDD patterns is derived from Evan's DDD book and DDD reference:
 
  * [Domain-Driven Design: Tackling Complexity in the Heart of Software](https://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215)
  * [DDD Reference](http://domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf)
 
+
+
+
 ## Semantic Rules
-The following semantic rules are either implicitely given by the domain model (see above) on which the language is base, or enforced by corresponding semantic checkers. Note that the model and the semantic rules express how we understand the DDD patterns and how they can be combined.
+The following semantic rules are either implicitly given by the domain model on which the language is based (see above), or enforced by corresponding semantic checkers. 
+
+Note that the model and the semantic rules express how we understand the DDD patterns and how they can be combined, and how we applied DDD on projects ourselves. Rationale: the literature is somewhat ambiguous.  
 
 **\#1: The relationship patterns Open Host Service (OHS), Published Language, Anticorruption Layer (ACL) and Conformist are not applicable for Partnership and Shared Kernel relationships.**
 A violation of this rule would lead to contradictions regarding the definitions of the patterns and how we understand them. In a Shared Kernel relationship, two bounded contexts share a subset of its domain model and thus, technically, share code. The interaction between the two bounded contexts happens via this shared code. The usage of the four mentioned patterns contradicts with this approach. The same applies to the very tightly coupled Partnership pattern. Even if the contexts do not share code, the two contexts can only succeed or fail together.
diff --git a/_docs/language-reference/language-reference.md b/_docs/language-reference/language-reference.md
index 78ea261..03a4d8a 100644
--- a/_docs/language-reference/language-reference.md
+++ b/_docs/language-reference/language-reference.md
@@ -3,16 +3,16 @@ title: CML Reference - Introduction
 permalink: /docs/language-reference/
 ---
 
-Within this section, we provide a documentation of all patterns and the according CML language features.
+This section of the online documentation covers all supported DDD patterns and the corresponding CML language features.
 
 ## Semantic Model
-On the [Language Semantics](/docs/language-model/) page you find a diagram illustrating the domain model on which the CML language is based.
-It helps to understand the structure of the language and semantics. The [page](/docs/language-model/) further describes all implemented semantic rules in a textual form.
+The [Language Semantics](/docs/language-model/) page contains a diagram illustrating the domain model on which the CML language is based. It helps to understand the structure of the language and semantics (for instance, the difference between bidirectional, symmetric context relationships and directed upstream-downstream relationships). 
+
+The [Language Model](/docs/language-model/) page further describes all implemented semantic rules in textual form.
 
 ## Strategic DDD Patterns
-The following strategic DDD patterns are supported by CML. 
-For detailed descriptions of the patterns itself we refer to Evan's [book](https://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215) 
-and his [DDD reference](http://domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf).
+The following strategic DDD patterns are supported by CML. For detailed descriptions of the patterns itself we refer to Evan's [original DDD book ("the blue book")](https://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215) 
+and his free [DDD reference](http://domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf).
 
 The syntax and semantic rules of all the patterns are documented on their individual pages:
 
@@ -20,31 +20,31 @@ The syntax and semantic rules of all the patterns are documented on their indivi
  * **[Bounded Context](/docs/bounded-context)**
  * **[Subdomain](/docs/subdomain)** (Core, Supporting, Generic)
  * **[Domain Vision Statement](/docs/domain-vision-statement)**
- * **[Partnership](/docs/partnership)**
- * **[Shared Kernel](/docs/shared-kernel)**
- * **[Customer/Supplier](/docs/customer-supplier)**
- * **[Conformist](/docs/conformist)**
+ * **[Partnership](/docs/partnership)** (P)
+ * **[Shared Kernel](/docs/shared-kernel)** (SK)
+ * **[Customer/Supplier](/docs/customer-supplier)** (C/S)
  * **[Open Host Service](/docs/open-host-service)** (OHS)
+ * **[Published Language](/docs/published-language)** (PL)
+ * **[Conformist](/docs/conformist)** (CF)
  * **[Anticorruption Layer](/docs/anticorruption-layer)** (ACL)
- * **[Published Language](/docs/published-language)**
  * **[Responsibility Layers](/docs/responsibility-layers)**
  * **[Knowledge Level](/docs/knowledge-level)**
- 
+ 
  
 ## Tactic DDD Patterns
-The tactic DDD part of the CML language, meaning all rules inside *aggregates*, are based on the [Sculptor DSL](https://github.com/sculptor/sculptor). Thus, we refer to their [documentation](http://sculptorgenerator.org/documentation/advanced-tutorial#domain-driven-design) for details regarding the tactic DDD patterns.
+The tactic DDD part of the CML language(all grammar rules inside *Aggregates*s that is), are based on the [Sculptor DSL](https://github.com/sculptor/sculptor). Thus, we refer to the [Sculptor documentation](http://sculptorgenerator.org/documentation/advanced-tutorial#domain-driven-design) for details regarding the tactic DDD patterns.
  
-However, the most important tactic DDD patterns we also use for our transformations (Service Cutter integration and plantUML generation) are the following:
+The most important tactic DDD patterns that we use in our [transformations (for instance, plantUML generation)](/docs/generators/generators) are the following:
  
  * **Module**
  * **[Aggregate](/docs/aggregate)** (and *Aggregate Root*)
  * **Entity**
+ * **Service** 
  * **Value Object**
  * **Domain Event**
  
-The following patterns are supported as well, but currently not used in the transformations:
- 
- * **Service**
+The following patterns can be used in CML models as well (but currently are not processed by in any transformation): 
+
  * **Repository**
   
-**Note:** The aggregate pattern implementation has been changed and no longer corresponds to Sculptors implementation. Therefore it is documented [here](/docs/aggregate). 
+*Note:* Our Aggregate pattern implementation is different from the one in Sculptor; it does not correspond to Sculptor's implementation. Therefore it is documented [here](/docs/aggregate).  

From c786a1f5751a13a22b4c98a58d8d0834427ae861 Mon Sep 17 00:00:00 2001
From: Zimmermann Olaf 
Date: Mon, 23 Mar 2020 15:52:36 +0100
Subject: [PATCH 5/9] AR and Generator start page

---
 .../architectural-refactorings.md             | 25 ++++++-------
 _docs/generators/generators.md                | 36 +++++++++----------
 2 files changed, 28 insertions(+), 33 deletions(-)

diff --git a/_docs/architectural-refactorings/architectural-refactorings.md b/_docs/architectural-refactorings/architectural-refactorings.md
index c2c4668..2a5d24a 100644
--- a/_docs/architectural-refactorings/architectural-refactorings.md
+++ b/_docs/architectural-refactorings/architectural-refactorings.md
@@ -4,12 +4,12 @@ permalink: /docs/architectural-refactorings/
 image: /img/cm-og-image.png
 ---
 
-Within this section, we provide a documentation of all architectural refactorings (ARs) available in the Context Mapper tool.
+This section provides a documentation of all [architectural refactorings (ARs)](https://www.infoq.com/articles/architectural-refactoring/) available in the Context Mapper tool.
 
-## Motivation: Why refactorings?
-The provided refactorings offer the advantage that the result is always a correct CML model which compiles without errors. 
-If you perform similar changes manually, you also have to fix upcoming errors within the [Context Map](/docs/context-map/) manually.
-The AR's ensure that corresponding references and dependencies in other parts of the model are respected and adjusted if necessary.
+## Motivation: Why Refactoring?
+The provided refactorings ensure that the result is always a correct CML model which compiles without errors. 
+If you perform similar changes manually, you also have to fix errors that occur manually within the [Context Map](/docs/context-map/).
+The ARs ensure that corresponding references and dependencies in other parts of the model are respected and adjusted if necessary.
 
 ## Architectural Refactoring Categories
 The ARs are divided into the following categories:
@@ -19,7 +19,7 @@ The ARs are divided into the following categories:
 
 ## Refactoring Overview
 The Context Mapper tool offers you a set of architectural refactorings which can be applied to your CML models. The refactorings shall
-support you with evolving and improving the architecture of your system.
+support you while evolving and improving the architecture of your system.
 
 ### Structural Refactorings
 We currently provide the following structural ARs:
@@ -44,21 +44,18 @@ The following ARs to change Context Map relationships are currently implemented:
 | Name                                                                                           | Subject                    | Description                                                                     | Input                      | Output                     |
 |------------------------------------------------------------------------------------------------|----------------------------|---------------------------------------------------------------------------------|----------------------------|----------------------------|
 | [**AR-10: Change Shared Kernel to Partnership**](/docs/ar-change-shared-kernel-to-partnership) | Shared Kernel relationship | Changes the type of a Shared Kernel relationship to a Partnership relationship. | Shared Kernel relationship | Partnership relationship   |
-| [**AR-11: Change Partnership to Shared Kernel**](/docs/ar-change-partnership-to-shared-kernel) | Partnership relationship   | Changes the type of a Partnership relationship to a Shared Kernel relationship. | Partnership relationship   | Shared Kernel relationship |
+| [**AR-11: Change Partnership to Shared Kernel**](/docs/ar-change-partnership-to-shared-kernel) | Partnership relationship   | Changes the type of a Partnership relationship to a Shared Kernel relationship. | Partnership relationship | Shared Kernel relationship |
 
 ## Examples
-Within our [examples repository](https://github.com/ContextMapper/context-mapper-examples) you can find [input and corresponding 
-output examples](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/architectural-refactorings) 
-for all ARs listed above.
+You can find [input and corresponding output examples](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/architectural-refactorings) for all ARs listed above in our [examples repository](https://github.com/ContextMapper/context-mapper-examples).
 
 ## How to apply Architectural Refactorings (ARs)
 Architectural refactorings can be applied within the Context Mapper Eclipse plugin by using the context menu in the DSL editor. With a
-right-click on a bounded context or an aggregate the **Context Mapper: Refactor** menu entry appears and lists all refactorings which are 
-applicable to the selected elements:
+right-click on a bounded context or an aggregate the **Context Mapper: Refactor** menu entry appears and lists all refactorings which are applicable to the selected elements:
 
 ![Architectural Refactoring Context Menu Example](/img/architectural-refactorings-context-menu.png)
 
-You can also use the Shift-Alt-T keybinding for quick access to the available refactorings (cursor must be on the object on which you want to start the refactoring).
+You can also use the Shift-Alt-T keybinding for quick access to the available refactorings (the cursor must be on the object on which you want to start the refactoring).
 
-**Note** that the context menu only shows ARs for which your selected model element fulfills the preconditions.
+*Note*: The context menu only shows ARs for which your selected model element fulfills the preconditions.
 The preconditions for all ARs are mentioned on the corresponding detail pages linked above. 
diff --git a/_docs/generators/generators.md b/_docs/generators/generators.md
index 8a27824..11271bd 100644
--- a/_docs/generators/generators.md
+++ b/_docs/generators/generators.md
@@ -4,31 +4,28 @@ permalink: /docs/generators/
 ---
 
 The Context Mapper generators provide transformations to derive graphical Context Maps, [PlantUML diagrams](http://plantuml.com/), 
-[MDSL](https://socadk.github.io/MDSL/) (micro-)service contracts, and [ServiceCutter input files](https://servicecutter.github.io/) from your 
-CML context map. In addition we provide a [generic generator](/docs/generic-freemarker-generator/) based on Freemarker which allows to generate arbitrary textual files.
+[Microservice Domain-Specific Langauge (MDSL)](https://socadk.github.io/MDSL/) (micro-)service contracts, and [ServiceCutter] ](https://servicecutter.github.io/) input files from your CML context map. We also provide a [generic, template-based generator](/docs/generic-freemarker-generator/) based on Freemarker which allows to generate arbitrary textual files.
 
 **Generators:**
- * [Graphical Context Maps](#graphical-context-maps)
- * [PlantUML Diagrams](#plantuml-diagrams)
- * [MDSL (Micro-)Service Contracts](#mdsl-micro-service-contracts)
- * [Service Cutter Input Files](#service-cutter-input-files)
- * [Generic Textual Generator (Freemarker Templating)](#generic-textual-generator-freemarker-templating)
+ * [Graphical context maps](#graphical-context-maps)
+ * [PlantUML diagrams](#plantuml-diagrams)
+ * [MDSL (micro-)service contracts](#mdsl-micro-service-contracts)
+ * [Service Cutter input files](#service-cutter-input-files)
+ * [Generic, template-based textual generator (Freemarker Templating)](#generic-textual-generator-freemarker-templating)
 
-The generator can be accessed through the Context Menu of the CML editor or with a right-click on the *.cml file in the project explorer. In the CML editor you can access all generators
-with the keybinding Shift-Alt-G quickly.
+The generator can be accessed through the Context Menu of the CML editor or with a right-click on the `*.cml` file in the project explorer. In the CML editor, you can access all generators with the keybinding Shift-Alt-G quickly.
 
 ## Graphical Context Maps
 The Context Map generator allows you to transform the CML Context Map into graphical representation inspired by the illustrations of 
 [Vernon](https://www.amazon.de/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577) and 
-[Brandolini](https://www.infoq.com/articles/ddd-contextmapping/). [Here](/docs/context-map-generator/) you can find out how to generate them.
+[Brandolini](https://www.infoq.com/articles/ddd-contextmapping/). You can find out how to generate them [here](/docs/context-map-generator/).
 
-An example Context Map produced with our generator:
+A sample Context Map produced with our generator is:
 ![Insurance Company Example Context Map](/img/context-map-generator-insurance-sample.png)
 
 ## PlantUML Diagrams
 You can generate [plantUML](http://plantuml.com/) component diagrams out of CML context maps. Additionally, the transformation 
-generates class diagrams for all bounded contexts. If the implemented subdomains contain entities, the generator produces class diagrams
-for these subdomains as well. [Here](/docs/plant-uml/) you can find out how to generate them.
+generates UML class diagrams for all bounded contexts. If the implemented subdomains contain entities, the generator produces class diagrams for these subdomains as well. [This page](/docs/plant-uml/) describes how to generate them.
 
 Example component diagram (DDD sample): 
 DDD Sample Component Diagram
@@ -37,11 +34,11 @@ Example class diagram (Cargo booking context):
 Cargo Booking Context
 
 ## MDSL (Micro-)Service Contracts
-With our [MDSL](https://socadk.github.io/MDSL/) generator you can generate (micro-)service contracts out of your Context Maps.
-The resulting contracts illustrate how you can derive (micro-)services from strategic DDD context maps and aim for providing 
-assistance regarding how your system can be implemented in an (micro-)service-oriented architecture.
+With our [MDSL](https://socadk.github.io/MDSL/) generator you can generate (micro-)service contracts from your Context Maps (or, more precisely, from upstream bounded contexts that expose at least one aggregate that contains at least one operation in a service or entity).
+The resulting contracts illustrate how you can derive (micro-)services from strategic DDD context maps and provide 
+assistance regarding how to implement your system as a (micro-)service-oriented architecture.
 
-This is an example [MDSL](https://socadk.github.io/MDSL/) service contract for our 
+This is an examplary [MDSL](https://socadk.github.io/MDSL/) service contract for our 
 [insurance example](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example): 
 
 
// Generated from DDD Context Map 'Insurance-Example_Context-Map.cml' at 21.10.2019 17:48:52 CEST.
@@ -94,5 +91,6 @@ Find out how to produce Service Cutter input to calculate possible service cuts
 ![Service Cutter DDD Sample](/img/service-cutter-ddd-sample.png)
 
 ## Generic Textual Generator (Freemarker)
-With the generic generator based on [Freemarker](https://freemarker.apache.org/) templates Context Mapper users are allowed to generate arbitrary text files from CML Context Maps.
-Learn more about this generator [here](/docs/generic-freemarker-generator/)
+The generic, template-based generator allows you to generate arbitrary text files from CML Context Maps. It uses [Freemarker](https://freemarker.apache.org/) as its template engine and exposes the entire CML content as an object tree whose elements can be injected into the template.
+
+Learn more about this generator [here](/docs/generic-freemarker-generator/).

From 3aa5471cdb977985c2538e014d823d1adf1582d1 Mon Sep 17 00:00:00 2001
From: Zimmermann Olaf 
Date: Mon, 23 Mar 2020 18:10:59 +0100
Subject: [PATCH 6/9] Remaining generator pages

---
 _docs/generators/context-map-generator.md     | 23 +++---
 _docs/generators/generators.md                |  2 +
 .../generic-freemarker-generator.md           | 74 ++++++++---------
 _docs/generators/mdsl.md                      | 82 ++++++++-----------
 _docs/generators/plant-uml.md                 | 19 ++---
 _docs/generators/service-cutter.md            | 33 ++++----
 _docs/language-reference/imports.md           |  9 +-
 .../event-sourcing-and-cqrs-modeling.md       |  4 +-
 8 files changed, 112 insertions(+), 134 deletions(-)

diff --git a/_docs/generators/context-map-generator.md b/_docs/generators/context-map-generator.md
index f9449ce..c56f5de 100644
--- a/_docs/generators/context-map-generator.md
+++ b/_docs/generators/context-map-generator.md
@@ -5,12 +5,12 @@ image: /img/context-mapper-example-context-map.png
 ---
 
 ## Introduction
-With our Context Map generator you can produce graphical representations of your Context Mapper DSL (CML) Context Maps. The visualization of the
-generated Context Maps is inspired by the illustrations of [Vernon](https://www.amazon.de/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577)
+Our Context Map generator produces graphical representations of Context Mapper DSL (CML) Context Maps. The visualization of the
+generated Context Maps is inspired by the illustration style proposed by [Vernon](https://www.amazon.de/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577)
 and [Brandolini](https://www.infoq.com/articles/ddd-contextmapping/).
 
 ## Examples
-The following CML Context Map represents the DDD cargo sample application: (find the complete CML file [here](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/ddd-sample)) 
+The following CML Context Map represents the DDD cargo sample application (find the complete CML file [here](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/ddd-sample)): 
 
 
ContextMap DDDSampleMap {
   contains CargoBookingContext
@@ -29,8 +29,8 @@ Using our generator produces the following graphical Context Map for you:
 
 ![DDD Cargo Sample Application Context Map](/img/context-map-generator-ddd-sample.png)
 
-As a second example, the following Context Map represents our [insurance company example](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example):
-(find the complete CML file [here](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example))
+As a second example, the following Context Map represents our [insurance company example](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example)
+(find the complete CML file [here](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example)):
 
 
ContextMap InsuranceContextMap {
   type = SYSTEM_LANDSCAPE
@@ -77,7 +77,7 @@ As a second example, the following Context Map represents our [insurance company
 }
 

 
-For this Context Map our generator produces the following graphical result:
+Our generator produces the following graphical result for the above Context Map:
 
 ![Insurance Company Example Context Map](/img/context-map-generator-insurance-sample.png)
 
@@ -85,12 +85,11 @@ For this Context Map our generator produces the following graphical result:
 The Context Map generator can be used within our Eclipse plugin as described below. 
 
 ### System Requirements
-The generator requires [Graphviz](https://www.graphviz.org/) to be installed on your system since it is based on it.
+The generator requires [Graphviz](https://www.graphviz.org/) to be installed on your system because it uses it behind the scenes:
 
  * Ensure [Graphviz](https://www.graphviz.org/) is installed on your machine.
- * Ensure the binaries of the [Graphviz](https://www.graphviz.org/) installation are part of your PATH environment variable and can be called from
-   the command line.
-    * Especially on Windows this is not the case after the installation of [Graphviz](https://www.graphviz.org/). The default installation path is
+ * Verify that the binaries of the [Graphviz](https://www.graphviz.org/) installation are part of your PATH environment variable and can be called from the command line, for instance by executing `dot -V` from the command line.  
+    * In Windows this is not the case after the installation of [Graphviz](https://www.graphviz.org/). The default installation path is
       `C:\Program Files (x86)\GraphvizX.XX`, which means you have to add `C:\Program Files (x86)\GraphvizX.XX\bin` to your PATH variable.
 
 ### Generating Context Maps
@@ -98,10 +97,10 @@ The generator can be called from the _Context Mapper_ context menu within the CM
 
 ![Context Map Generator Context Menu](/img/context-map-generator-context-menu.png)
 
-A dialog will allow you to adjust the following **parameters** before the Context Map is generated:
+A dialog will allow you to adjust the following *parameters* before the Context Map is generated:
 
  * Formats which shall be exported (PNG, SVG, DOT)
  * Size of the image (you can fix the width or height of the image)
  * Spacing factor (you can increase or decrease the spacing between edges, which can help to handle overlapping labels)
  
-All the diagrams will be generated into the **src-gen** folder.
+All the diagrams will be generated into the *src-gen* folder.
diff --git a/_docs/generators/generators.md b/_docs/generators/generators.md
index 11271bd..2ac16a6 100644
--- a/_docs/generators/generators.md
+++ b/_docs/generators/generators.md
@@ -94,3 +94,5 @@ Find out how to produce Service Cutter input to calculate possible service cuts
 The generic, template-based generator allows you to generate arbitrary text files from CML Context Maps. It uses [Freemarker](https://freemarker.apache.org/) as its template engine and exposes the entire CML content as an object tree whose elements can be injected into the template.
 
 Learn more about this generator [here](/docs/generic-freemarker-generator/).
+
+
diff --git a/_docs/generators/generic-freemarker-generator.md b/_docs/generators/generic-freemarker-generator.md
index defc410..fa9c876 100644
--- a/_docs/generators/generic-freemarker-generator.md
+++ b/_docs/generators/generic-freemarker-generator.md
@@ -10,8 +10,7 @@ permalink: /docs/generic-freemarker-generator/
  * [Example Templates](#example-templates)
 
 ## Introduction
-With the generic generator based on [Freemarker](https://freemarker.apache.org/) templates Context Mapper users are allowed to generate arbitrary text files from CML Context Maps.
-By providing a corresponding [Freemarker](https://freemarker.apache.org/) template (_*.ftl_ file) one can generate for example Markdown, XML, or any other textual output formats.
+The generic generator is based on [Freemarker](https://freemarker.apache.org/) templates. It allows Context Mapper users to generate arbitrary text files from CML Context Maps. One can generate for example Markdown, JSON, XML, or any other textual output formats by providing a corresponding [Freemarker](https://freemarker.apache.org/) template (_*.ftl_ file).
 
 ### Simple Example
 This simple example illustrates how the generator works. The following Freemarker template outputs the names of all Bounded Contexts on the Context Map:
@@ -39,16 +38,16 @@ DebtCollection
 ```
 
 ## Data Model
-In order to write our Freemarker templates you have to know our data model. In the following we provide an overview over this CML model.
+In order to write your own Freemarker templates, you have to know the data model exposed by Context Mapper. In the following we provide an overview over this CML model.
 
 

 Note: We do not document the tactic DDD parts within Bounded Contexts in all details. In case your template needs information on that level please use 
 our JavaDoc documentation
-to get the necessary information about the data model.
+to obtain the necessary information about the data model.
 

 
 

-Note: The variable names of the model documented below must be used case-sensitive in Freemarker templates.
+Note: The variable names of the model documented below must be used case-sensitively in Freemarker templates.
 

 
 ### Root Level
@@ -78,11 +77,10 @@ The root level of the model contains the following elements:
   +- userName                      name of the current system user
 ```
 
-The corresponding CML objects and their syntax can be found in our language reference: [Context Map](/docs/context-map/), [Bounded Context](/docs/bounded-context/), 
-[Domains and Subdomains](/docs/subdomain/), [imports](/docs/imports/), [use cases](/docs/aggregate/#use-case-declaration).
+The corresponding CML objects and their syntax can be found in our language reference: [Context Map](/docs/context-map/), [Bounded Context](/docs/bounded-context/), [Domains and Subdomains](/docs/subdomain/), [imports](/docs/imports/), [use cases](/docs/aggregate/#use-case-declaration).
 
 ### Context Map
-The _contextMap_ root element of the model contains the following data: (the illustrated values are just examples)
+The _contextMap_ root element of the model contains the following data (the values in double quotes `"..."`are just examples):
 
 ```text
 contextMap
@@ -99,7 +97,7 @@ contextMap
 ```
 
 #### Relationships
-If you use relationships you must respect the different types as illustrated in our language [meta model](/docs/language-model/). The following types of relationships exist:
+If you use relationships, you must respect the different types as illustrated in our language [meta model](/docs/language-model/). The following types of relationships exist:
 
  * _SymmetricRelationship_
    * _Partnership_
@@ -159,8 +157,10 @@ relationship
       +- name = "INFLUENCER"
 ```
 
+
+
 #### Relationship Type Checking
-To respect the different structures when processing the relationship list we provide a method that allows you to check the type of the relationship:
+To respect the different structures when processing the relationship list, we provide a method that allows you to check the type of the relationship:
 
 ```ftl
 <#if instanceOf(relationship, SymmetricRelationship)>
@@ -174,7 +174,7 @@ To respect the different structures when processing the relationship list we pro
 
 ```
 
-You can also check which kind of relationship concretely it is:
+You can also check the type of concrete relationship:
 
 ```ftl
 <#if instanceOf(relationship, Partnership)>
@@ -255,9 +255,7 @@ boundedContext
   +- aggregates                    List of Aggregate objects
 ```
 
-**Note:** The attribute _implementedDomainParts_ of the _BoundedContext_ returns a list of _DomainParts_. A _DomainPart_ can either be a _Domain_ or a _Subdomain_. Both have a _name_
-and a _domainVisionStatement_. As long as you only use these two attributes you don't have to check for the type. However, if you want to access the _type_ attribute of a _Subdomain_
-you have to check if the _DomainPart_ is a _Subdomain_ first:
+**Note:** The attribute _implementedDomainParts_ of the _BoundedContext_ returns a list of _DomainParts_. A _DomainPart_ can either be a _Domain_ or a _Subdomain_. Both have a _name_ and a _domainVisionStatement_. As long as you only use these two attributes you don't have to check for the type. However, if you want to access the _type_ attribute of a _Subdomain_ you have to check if the _DomainPart_ is a _Subdomain_ first:
 
 ```ftl
 <#if instanceOf(domainPart, Subdomain)>
@@ -266,7 +264,7 @@ you have to check if the _DomainPart_ is a _Subdomain_ first:
 ```
 
 ### Aggregate
-Bounded Contexts contain a set of Aggregates which have the following structure (rough):
+Bounded Contexts contain a set of Aggregates that have the following structure (rough sketch, the JavaDoc has the details):
 
 ```text
 aggregate
@@ -300,10 +298,10 @@ aggregate
   +- domainObjects                 List of SimpleDomainObject objects (Sculptor)
 ```
 
-We do not document the structures below Aggregates (Sculptor) at this point. To use them, please consult the 
+We do not document the structures below Aggregates (Sculptor) here. Please consult the 
 [JavaDoc](https://www.javadoc.io/doc/org.contextmapper/context-mapper-dsl/latest/org/contextmapper/dsl/contextMappingDSL/Aggregate.html) documentation of the Aggregate.
 
-**Note**: The _domainObjects_ list contains all domain objects such as Entities, Value Objects, etc. In total Sculptor defines the following type hierarchy:
+**Note**: The _domainObjects_ list contains all domain objects such as Entities, Value Objects, etc. Sculptor defines the following overall type hierarchy:
 
  * SimpleDomainObject
    * BasicType
@@ -317,7 +315,7 @@ We do not document the structures below Aggregates (Sculptor) at this point. To
    * Enum
    * Trait
    
-To respect the different structures of these types you can use our _instanceOf_ method again:
+To respect the different structures of these types, you again can use our _instanceOf_ method:
 
 ```ftl
 <#if instanceOf(domainObject, Entity)>
@@ -325,12 +323,11 @@ To respect the different structures of these types you can use our _instanceOf_
 
 ```
 
-As already mentioned you find the structure of all those domain objects in our 
+As already mentioned, you find the structure of all these domain objects in our 
 [JavaDoc](https://www.javadoc.io/doc/org.contextmapper/context-mapper-dsl/latest/org/contextmapper/dsl/contextMappingDSL/Aggregate.html) documentation.
 
 ### Domains
-The _domains_ root element of the model contains a list of _DomainPart_ objects which can either be _Domains_ or _Subdomains_. Use our _instanceOf_ method to check of which type
-a _DomainPart_ is:
+The _domains_ root element of the model contains a list of _DomainPart_ objects which can either be _Domains_ or _Subdomains_. Use our _instanceOf_ method to check of which type a _DomainPart_ is:
 
 ```ftl
 <#if instanceOf(domainPart, Subdomain)>
@@ -367,8 +364,7 @@ subdomain
 ```
 
 ### Imports
-CML models can import other files via imports. The mechanism is explained [here](/docs/imports/). Imports can be accessed on the root level of the model (_imports_) and have 
-the following structure:
+CML models can import other files via imports. The mechanism is explained [here](/docs/imports/). Imports can be accessed on the root level of the model (_imports_) and have the following structure:
 
 ```text
 import
@@ -412,13 +408,13 @@ The following additional attributes are currently available on the root level of
 
  * _timestamp:_ generation time stamp (for example _26.02.2020 17:20:40 CET_)
  * _filename:_ name of the CML file (for example _ExampleModel.cml_)
+ 
 
 ## Helper Functions
-The following functions can be used in the Freemarker templates and help processing the model described above:
+The following functions can be used in the Freemarker templates to help processing the model described above:
 
 ### Bounded Context Filtering
-The functions _filterStructuralBoundedContexts_ and _filterTeams_ can be used to filter teams and Bounded Contexts which are not teams respectively. The following example lists all Bounded Contexts
-which are not teams:
+The functions _filterStructuralBoundedContexts_ and _filterTeams_ can be used to filter teams and Bounded Contexts which are not teams respectively. The following example lists all Bounded Contexts that are not teams:
 
 ```ftl
 <#list filterStructuralBoundedContexts(boundedContexts) as bc>
@@ -434,8 +430,7 @@ This example on the other hand lists all teams:
 ```
 
 ### Type Checking
-The meta-model behind CML contains a few inheritance hierarchies which make it unavoidable that you sometimes have to check of which type an object is. Examples with relationships and
-domains vs. subdomains have already been shown above. The function _instanceOf_ allows to check which type of relationship or subdomain an object has:
+The meta-model behind CML contains a few inheritance hierarchies which make it unavoidable that you sometimes have to check of which type an object is. Examples with relationships and domains vs. subdomains have already been shown above. The function _instanceOf_ allows to check which type of relationship or subdomain an object has:
 
 ```ftl
 <#if instanceOf(relationship, UpstreamDownstreamRelationship)>
@@ -451,11 +446,9 @@ domains vs. subdomains have already been shown above. The function _instanceOf_
 
 ### Get Type String of _ComplexType_
 If you work on the tactic DDD level with attributes and methods (parameters and return types) you may want to render the type of an attribute, parameter, or return type.
-This part of the DSL is based on [Sculptor](http://sculptorgenerator.org/) and the types are typically instances of the 
-[ComplexType](https://www.javadoc.io/doc/org.contextmapper/context-mapper-dsl/latest/org/contextmapper/tactic/dsl/tacticdsl/ComplexType.html) object. Depending on if it is 
-primitive type or a reference to another type, rendering the type as a string is quite cumbersome. The function _getType_ which takes a 
-[ComplexType](https://www.javadoc.io/doc/org.contextmapper/context-mapper-dsl/latest/org/contextmapper/tactic/dsl/tacticdsl/ComplexType.html) as a parameter returns a simple string 
-representing the type:
+This part of the DSL is based on [Sculptor](http://sculptorgenerator.org/), and the types are typically instances of the 
+[ComplexType](https://www.javadoc.io/doc/org.contextmapper/context-mapper-dsl/latest/org/contextmapper/tactic/dsl/tacticdsl/ComplexType.html) object. Depending on if it is primitive type or a reference to another type, rendering the type as a string is quite cumbersome. The function _getType_ which takes a 
+[ComplexType](https://www.javadoc.io/doc/org.contextmapper/context-mapper-dsl/latest/org/contextmapper/tactic/dsl/tacticdsl/ComplexType.html) as a parameter returns a simple string representing the type:
 
 ```ftl
 <#list simpleDomainObject.operations as operation>
@@ -464,29 +457,28 @@ representing the type:
 ```
 
 ## User Guide
-To use the generic generator based on [Freemarker](https://freemarker.apache.org/) you need two files within your Eclipse workspace:
+To use our generic, [Freemarker](https://freemarker.apache.org/ template-based generator, you need two files within your Eclipse workspace:
 
  * The input CML model (*.cml)
  * The [Freemarker](https://freemarker.apache.org/) template (*.ftl)
  
- With a right-click on the CML file or within the CML editor you can start the generator. You find it in the _Context Mapper_ context menu:
+ With a right-click on the CML file or within the CML editor, you can start the generator. You find it in the _Context Mapper_ context menu:
  
  ![Generic Textual Generator Context Menu](/img/generic-generator-context-menu.png)
  
- A dialog allows you to select a [Freemarker](https://freemarker.apache.org/) template (*.ftl file) which must be located somewhere in your workspace:
+ A dialog allows you to select a [Freemarker](https://freemarker.apache.org/) template (*.ftl file), which must be located somewhere in your workspace:
  
  ![Generic Textual Generator Dialog](/img/generic-generator-dialog.png)
  
- By finishing the dialog you generate the required file:
+You generate the required file when finishing the dialog:
  
  ![Generic Textual Generator Dialog](/img/generic-generator-result.png)
 
 ### Freemarker Version
-Context Mapper uses [Freemarker](https://freemarker.apache.org/) in version 2.3.30.
+Context Mapper uses [Freemarker](https://freemarker.apache.org/), currently Version 2.3.30.
 
 ## Example Templates
-With the Context Mapper Eclipse plugin we also deliver example Freemarker templates. Use the _Freemarker Generator Template Examples_ wizard via _File -> New -> Other..._
-to create the sample project containing the Freemarker templates:
+The Context Mapper Eclipse plugin comes with sample Freemarker templates. Use the _Freemarker Generator Template Examples_ wizard via _File -> New -> Other..._ to create the sample project containing the Freemarker templates: 
 
 ![Create Sample Project with Freemarker Templates (1)](/img/screenshot-new-freemarker-example-project-1.png)
 
@@ -494,4 +486,4 @@ to create the sample project containing the Freemarker templates:
 
 The project currently contains the following example templates:
 
- * Ubiquitous language glossary written in Markdown
+ * Ubiquitous language glossary written in Markdown 
diff --git a/_docs/generators/mdsl.md b/_docs/generators/mdsl.md
index 70303ec..c2726f9 100644
--- a/_docs/generators/mdsl.md
+++ b/_docs/generators/mdsl.md
@@ -4,16 +4,14 @@ permalink: /docs/mdsl/
 ---
 
 ## Introduction and Motivation
-The [Microservices Domain Specific Language (MDSL)](https://socadk.github.io/MDSL/) is a DSL to specify (micro-)service contracts 
-and data representations realizing the API Description pattern from [Microservice API Patterns (MAP)](https://microservice-api-patterns.org/).
+The [Microservices Domain Specific Language (MDSL)](https://socadk.github.io/MDSL/) is a [Domain-Specific Language (DSL)](https://en.wikipedia.org/wiki/Domain-specific_language)) to specify (micro-)service contracts and data representations, jointly realizing the technical part of the [API Description](https://microservice-api-patterns.org/patterns/foundation/APIDescription) pattern from [Microservice API Patterns (MAP)](https://microservice-api-patterns.org/).
 
-With our [MDSL](https://socadk.github.io/MDSL/) generator you can automatically produce (micro-)service contracts out of your strategic
-DDD context map written in CML. The generator creates the contracts according to the following mapping, which reflects our proposal
-how we would derive (micro-)services from models based on strategic DDD. The generator aims for providing assistance regarding how your
-system can be implemented in an (micro-)service-oriented architecture.
+Our [MDSL](https://socadk.github.io/MDSL/) generator automatically produces (micro-)service contracts out of strategic
+DDD context maps written in CML. The generator creates the contracts according to the following mapping, which reflects our proposal
+how we would derive (micro-)services from models based on strategic DDD . The generator aims at providing assistance regarding how your system can be implemented as a (micro-)service-oriented architecture.
 
 ### Language Mapping
-
+
 | CML Input                                                                                                                        | MDSL Output                                        | Description                                                                                                                                                                                                                                                             |
 |----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | Upstream Bounded Contexts from upstream-downstream [relationships](/docs/context-map/#relationships)                             | Service Specification (API description)            | We create one service specification for each upstream Bounded Context of your Context Map.                                                                                                                                                                              |
@@ -24,7 +22,7 @@ system can be implemented in an (micro-)service-oriented architecture.
 | Downstream Bounded Contexts from upstream-downstream [relationships](/docs/context-map/#relationships)                           | API client                                         | Downstream Bounded Contexts are mapped to corresponding API clients.                                                                                                                                                                                                    |
 
 ### Data Type Mapping
-The base/primitive types are mapped as follows:
+The base/primitive types are mapped to [Atomic Parameters](https://microservice-api-patterns.org/patterns/structure/representationElements/AtomicParameter) as this:
 
 | CML type         | MDSL type                                   |
 |------------------|---------------------------------------------|
@@ -37,12 +35,10 @@ The base/primitive types are mapped as follows:
 | Date             | D<string> (no date available in MDSL) |
 
 

-Note: Types in CML are case sensitive. For example: If you write "string" instead of "String", you create a new abstract
-data type instead of using the primitive type "String".
+Note: Types in CML are case-sensitive. For example: If you write "string" instead of "String", you create a new abstract data type instead of using the primitive type "String".
 

 
-If you declare a method with multiple parameters or refer to an object (such as entity or value object) in CML, we generate a corresponding
-parameter tree. For example the following entity would be mapped to the parameter tree below:
+If you declare a method with multiple parameters or refer to an object (such as Entity or Value Object) in CML, we generate a corresponding [Parameter Tree(https://microservice-api-patterns.org/patterns/structure/representationElements/ParameterTree). For example the following entity would be mapped to the (rather flat) parameter tree below:
 
 CML input:
 ```
@@ -57,13 +53,13 @@ MDSL data type result:
 
data type Address { "street":D<string>, "lockbox":D<string>?, "postalCode":D<int>, "city":D<string> }
 

 
-All abstract data types which are not base types and not specified in CML (no references to objects) will produce an abstract, 
-unspecified element in [MDSL](https://socadk.github.io/MDSL/), as the following example illustrates:
+All abstract data types that are not base types and not specified in CML (no references to objects) will produce an abstract, 
+unspecified placeholder element `P` in [MDSL](https://socadk.github.io/MDSL/), as the following example illustrates:
 
data type JustAnUnspecifiedParameterType P
 

 
 ### Example
-An example [MDSL](https://socadk.github.io/MDSL/) API description looks as follows: 
+An exemplary API description in [MDSL](https://socadk.github.io/MDSL/), generated by Context Mapper, is: 
 
// Generated from DDD Context Map 'Insurance-Example_Context-Map.cml' at 21.10.2019 17:48:52 CEST.
 API description CustomerManagementContextAPI
 usage context PUBLIC_API for BACKEND_INTEGRATION
@@ -106,12 +102,11 @@ An example [MDSL](https://socadk.github.io/MDSL/) API description looks as follo
 IPA
 

 
-**Note:** This example has been generated from our [insurance example](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example) 
-which you can find in our [examples repository](https://github.com/ContextMapper/context-mapper-examples).
+*Note:* This example has been generated from our [insurance example](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example), which you can find in our [examples repository](https://github.com/ContextMapper/context-mapper-examples).
 
-### MAP Pattern Decorators
-The MDSL language allows modelers to specify the roles of endpoints and operations according to the MAP ([https://microservice-api-patterns.org/](https://microservice-api-patterns.org/)) 
-responsibility patterns. Our generators match the corresponding pattern names in comments on Aggregates and methods. The following CML code illustrates how
+### Microservice API Patterns (MAP) Decorators
+The MDSL language allows modelers to specify the roles of endpoints and operations according to the endpoint- and operation-level 
+[responsibility patterns in MAP](https://microservice-api-patterns.org/patterns/responsibility/). Our generators match the corresponding pattern names in comments on Aggregates and methods. The following CML code illustrates how
 the MAP patterns can be added in CML. In this case we use the _Information Holder Resource_ pattern on the Aggregate level and the _Retrieval Operation_ pattern
 on the method level:
 
@@ -137,8 +132,7 @@ on the method level:
 }
 
 
 
-The patterns are detected by our generator and mapped to the corresponding language features of MDSL. The following MDSL code illustrates the resulting resource
-for the Aggregate specified above:
+The patterns are detected by our generator and mapped to the corresponding language features of MDSL. The following MDSL code illustrates the resulting resource for the Aggregate specified above:
 
 
data type Address { "street":D<string>, "postalCode":D<int>, "city":D<string> }
 data type AddressId P
@@ -154,52 +148,50 @@ for the Aggregate specified above:
         payload Address
 

 
-As illustrated above, the patterns on the resource level are added with the _serves as_ keyword and on the operation level with the _with responsibility_ keyword.
-In the following we list the supported patterns:
+As illustrated above, the patterns on the endpoint/resource level are added with the _serves as_ keyword and on the operation level with the _with responsibility_ keyword. In the following we list the supported patterns:
 
 #### Endpoint Role Patterns
  * [PROCESSING_RESOURCE](https://microservice-api-patterns.org/patterns/responsibility/endpointRoles/ProcessingResource)
  * [INFORMATION_HOLDER_RESOURCE](https://microservice-api-patterns.org/patterns/responsibility/endpointRoles/InformationHolderResource)
- * OPERATIONAL_DATA_HOLDER
+ * [OPERATIONAL_DATA_HOLDER](https://microservice-api-patterns.org/patterns/responsibility/informationHolderEndpoints/OperationalDataHolder)
  * [MASTER_DATA_HOLDER](https://microservice-api-patterns.org/patterns/responsibility/informationHolderEndpoints/MasterDataHolder)
- * REFERENCE_DATA_HOLDER
+ * [REFERENCE_DATA_HOLDER](https://microservice-api-patterns.org/patterns/responsibility/informationHolderEndpoints/ReferenceDataHolder)
  * [TRANSFER_RESOURCE](https://microservice-api-patterns.org/patterns/responsibility/informationHolderEndpoints/TransferResource)
  * [LOOKUP_RESOURCE](https://microservice-api-patterns.org/patterns/responsibility/informationHolderEndpoints/LookupResource)
 
-#### Operation Role Patterns
+#### Operation Responsibility Patterns
  * [COMPUTATION_FUNCTION](https://microservice-api-patterns.org/patterns/responsibility/processingResponsibilities/ComputationFunction)
- * NOTIFICATION_OPERATION
+ * [NOTIFICATION_OPERATION](https://microservice-api-patterns.org/patterns/responsibility/processingResponsibilities/NotificationOperation)
  * [RETRIEVAL_OPERATION](https://microservice-api-patterns.org/patterns/responsibility/processingResponsibilities/RetrievalOperation)
- * STATE_TRANSITION_OPERATION
- * [EVENT_PROCESSOR](https://microservice-api-patterns.org/patterns/responsibility/processingResponsibilities/EventProcessor)
- * [BUSINESS_ACTIVITY_PROCESSOR](https://microservice-api-patterns.org/patterns/responsibility/processingResponsibilities/BusinessActivityProcessor)
+ * [STATE_TRANSITION_OPERATION](https://microservice-api-patterns.org/patterns/responsibility/processingResponsibilities/StateTransitionOperation)
+ 
+
+Please refer to the pattern texts on the MAP website for explanations of these decorators.
 
 ## User Guide
 You can generate [MDSL](https://socadk.github.io/MDSL/) (micro-)service contracts from your CML model as follows.
 
-With a right-click to your CML-file in Eclipse you will find a **Context Mapper** context menu. With the action **MDSL:
-Generate Service Contracts** you generate the contracts for all upstreams in your Context Map:
+When you a right-click on a CML file in Eclipse, you a **Context Mapper** context menu will pop up. The action *MDSL:
+Generate Service Contracts* allows you to generate the contracts for all upstreams in your Context Map:
 
 ![MDSL Generator](/img/mdsl-generator-1.png)
 
 

 Note that the Context Mapper menu entry is also available within the context menu uf the CML editor. 
-(right-click anywhere in the editor)
+(right-click anywhere in the editor).
 

 
-All [MDSL](https://socadk.github.io/MDSL/) files will be generated into the **src-gen** folder of your project:
+All [MDSL](https://socadk.github.io/MDSL/) files will be generated into the **src-gen** folder of the project:
 
 ![MDSL Generator Result](/img/mdsl-generator-2.png)
 
 

-Note: The MDSL Eclipse plugin is not yet available for download (update site). At the moment you can open the *.mdsl 
-files with a text editor only (no syntax highlighting and editor support available yet).
+Note: The MDSL Eclipse plugin is not yet available for download on an Eclipse update site. At the moment you can open the `*.mdsl` files with a text editor only (with no syntax highlighting and editor support). You can also request access to the MDSL repository on GitHub by [contacting the MAP team](https://microservice-api-patterns.org/about).
 

 
 ### Protected Regions
-After you generated an MDSL contract you can add protected regions for **data types**, **endpoint types**, **API providers**, and **API clients**
-if you want to modify parts of the contract and protect them from being overwritten. The following example shows the corresponding comments needed to begin and
-end the four different protected regions:
+After you have generated an MDSL contract, you can add protected regions for **data types**, **endpoint types**, **API providers**, and **API clients** if you want to modify parts of the contract and protect them from being overwritten. The following example shows the corresponding comments that are required to begin and end the four different protected regions:
 
 
// Generated from DDD Context Map 'Insurance-Example_Context-Map.cml' at 21.10.2019 17:48:52 CEST.
 API description CustomerManagementContextAPI
@@ -259,12 +251,9 @@ end the four different protected regions:
 IPA
 

 
-The protected regions allow you to move _data types_, _endpoints_, _API providers_, and _API clients_ into its corresponding protected
-region so that they are not overwritten at re-generation. Thus, you can call the MDSL generator on the same file again and all objects
-within a protected region will not be changed. 
+The protected regions allow you to guard _data types_, _endpoints_, _API providers_, and _API clients_ into so that they are not overwritten at re-generation. Thus, you can call the MDSL generator on the same file again and all objects within a protected region will still be there and remain unchanged. 
 
-For example, you can move a set of _data types_ into the corresponding protected region 
-if you changed the data types manually after generation and want to protect them:
+For example, you can move a set of _data types_ into the corresponding protected region if you changed the data types manually after generation and want to protect them:
 
 
// Generated from DDD Context Map 'Insurance-Example_Context-Map.cml' at 21.10.2019 17:48:52 CEST.
 API description CustomerManagementContextAPI
@@ -285,5 +274,4 @@ if you changed the data types manually after generation and want to protect them
 

 
 ## MDSL Support
-The current version of our MDSL generator is compatible with the MDSL version _1.1.0_. For further questions regarding [MDSL](https://socadk.github.io/MDSL/) please visit the website [https://socadk.github.io/MDSL](https://socadk.github.io/MDSL)
-or contact Olaf Zimmermann.
+The current version of our MDSL generator is compatible with the MDSL version _1.2.0_. For further questions regarding [MDSL](https://socadk.github.io/MDSL/), please visit its website [https://socadk.github.io/MDSL](https://socadk.github.io/MDSL).
diff --git a/_docs/generators/plant-uml.md b/_docs/generators/plant-uml.md
index a89b967..849ead9 100644
--- a/_docs/generators/plant-uml.md
+++ b/_docs/generators/plant-uml.md
@@ -4,18 +4,13 @@ permalink: /docs/plant-uml/
 ---
 
 ## Introduction and Motivation
-The [PlantUML](http://plantuml.com/) tool allows to quickly write UML diagrams. With our PlantUML generator you can generate a UML component
-diagram and class diagrams for every Bounded Context of your model. If the implemented Subdomains contain entities, the generator produces 
-class diagrams for these subdomains as well. Thereby we offer a transformation from our DSL into a graphical representation of the system. 
-The component diagram illustrates all Bounded Contexts and their relationships, while the class diagrams show the domain models of the 
-Bounded Contexts and Subdomains if you used the [Tactic DDD Syntax](/docs/tactic-ddd/) to model them. 
+The [PlantUML](http://plantuml.com/) tool let you create UML diagrams quickly. You can generate UML component diagrams representing entire Context Maps and UML class diagrams for each Bounded Context in your model. If the implemented Subdomains contain Entities, the generator produces class diagrams for these Subdomains as well. We offer a transformation from our DSL into a graphical representation of the system this way. The component diagram illustrates all Bounded Contexts and their relationships, while the class diagrams show the domain models of the Bounded Contexts and Subdomains (if you used the [Tactic DDD Syntax](/docs/tactic-ddd/) to specify them). 
 
 ## User Guide
-The following section describes how you use the PlantUML generators to create the 
-UML component and class diagrams of your modeled system.
+The following section describes how you use the PlantUML generators to create the UML component and class diagrams of your modeled system.
 
 ### Generating plantUML Diagrams
-We assume you have a CML file with your model in Eclipse (with our plugin installed). With a right-click to the CML-file you will find a **Context Mapper** context menu. With the action **PlantUML: Generate Diagrams** you generate all the plantUML diagrams for your context map:
+We assume you have a CML file with your model in Eclipse (with our plugin installed). Right-clicking on the CML-file, you will find a **Context Mapper** context menu. With the action **PlantUML: Generate Diagrams** you generate all the plantUML diagrams for your Context Map:
 
 ![PlantUML Generator](/img/plantuml-generation-1.png)
 
@@ -25,18 +20,20 @@ We assume you have a CML file with your model in Eclipse (with our plugin instal
 

 
 All the diagrams will be generated into the **src-gen** folder. If you have installed one of the recommended plantUML Eclipse plugins 
-(see recommendations [here](/docs/getting-started/)), you can directly open and view the diagrams in eclipse:
+(see recommendations [here](/docs/getting-started/)), you can directly open and view the diagrams in Eclipse:
 
 ![PlantUML View in Eclipse](/img/plantuml-generation-2.png)
 
 #### UML Component Diagram
-The transformation will generate one component diagram for your context map, showing the bounded contexts and its relationships. The component diagram for our insurance example:
+The transformation will generate one component diagram for your context map, showing the Bounded Contexts and its relationships. The component diagram for our insurance example is:
 
 ![PlantUML Component Diagram](/img/plantuml-insurance-example-component-diagram.png)
 
 #### UML Class Diagram
-Further, the transformation generates a class diagram for every bounded context. An example from the insurance scenario:
+The transformation generates a class diagram for every bounded context as well. An example from the insurance scenario is:
 
 ![PlantUML Class Diagram](/img/plantuml-insurance-example-class-diagram.png)
 
+Once you have the generated `.puml` files available, you can of course not only view them in Eclipse but also process them further. For instance, they can be integrated into Markdown and [pandoc](https://pandoc.org/extras.html) nicely.
+
 
diff --git a/_docs/generators/service-cutter.md b/_docs/generators/service-cutter.md
index 3e12ab5..e372a70 100644
--- a/_docs/generators/service-cutter.md
+++ b/_docs/generators/service-cutter.md
@@ -4,64 +4,65 @@ permalink: /docs/service-cutter/
 ---
 
 ## Introduction and Motivation
-The [Service Cutter](http://servicecutter.github.io/) tool provides a structured way to service decomposition. Our _Service Cutter Input Generators_ allow you to generate
-the input files for [Service Cutter](http://servicecutter.github.io/). Thereby you can generate suggestions how to further decompose 
-your modeled system.
+The [Service Cutter](http://servicecutter.github.io/) tool provides a structured way to service decomposition. Our _Service Cutter Input Generators_ allow you to generate the [input files for Service Cutter](https://github.com/ServiceCutter/ServiceCutter/wiki/User-Representations). The prototypical integration of Service Cutter demonstrates the opportunity to generate suggestions how to further decompose a context-modeled system.
 
-For more information about Service Cutter we refer to the projects wiki and the paper:
+For more information about Service Cutter we refer to its projects wiki and two publications on it:
 
  * [Service Cutter Wiki](https://github.com/ServiceCutter/ServiceCutter/wiki)
  * [Service Cutter: A Systematic Approach to Service Decomposition (Paper)](https://link.springer.com/chapter/10.1007/978-3-319-44482-6_12)
  * [Service Cutter: A Systematic Approach to Service Decomposition (HSR Bachelor Thesis)](https://eprints.hsr.ch/476/)
 
 ## User Guide
-The following sections describe how you use the Service Cutter generators to create the 
-[Service Cutter](http://servicecutter.github.io/) input files.
+The following sections describe how to use the Service Cutter generators and create the input files for Service Cutter.
 
 ### Generate Entity Relationship Model File
-Service Cutter uses an ERD-file based on entities and nanoentities to describe the applications structure, the first input. 
+Service Cutter uses an [Entity-Relationship Model](https://github.com/ServiceCutter/ServiceCutter/wiki/ERM) Diagram (ERD) file that contains entities and nanoentities to describe the applications structure as its first and mandatory input. 
 
-We assume you have a CML file with your model in Eclipse (with our plugin installed). With a right-click to the CML-file you will find a **Context Mapper** context menu. With the action **Service Cutter: Generate Input File (JSON)** you generate the Service Cutter ERD file in the required JSON format:
+We assume you have a CML file with your model in Eclipse (with our plugin installed). A right-click to the CML-file will guide you to a **Context Mapper** context menu. When selecting the action **Service Cutter: Generate Input File (JSON)**, you generate the Service Cutter ERD file in the required JSON format:
 
 ![Generate ServiceCutter ERD File](/img/service-cutter-input-generation-1.png)
 
 

-Note that the Context Mapper menu entry is also available within the context menu uf the CML editor. 
-(right-click anywhere in the editor)
+Note that the Context Mapper menu entry is also available within the context menu uf the CML editor 
+(right-click anywhere in the editor).
 

 
 ### Generate SCL File
-The second input file for Service Cutter is representing its **User representations**. Service Cutter takes them in JSON format, but since there is some manual work needed to create them, we implemented another DSL which makes this much easier. Those files have the file extension **scl**, for **Service Cutter Language**.
+The second input file for Service Cutter deals with additional *User representations*. Service Cutter takes them in JSON format, but  there is some manual work required to create these file. Hence, we implemented another DSL which makes this step much easier. These files have the file extension `*.scl*` (for *Service Cutter Language*).
 
-A SCL file can be generated out of a CML file. Again, with a right-click to the CML-file you will find the **Context Mapper** context menu. With the action **Service Cutter: Initialize User Representations File (Exemplary)** you can initialize your SCL file:
+A SCL file can be generated out of a CML file. Again, a right-click to the CML-file will open the **Context Mapper** context menu. You can initialize your SCL file with the action **Service Cutter: Initialize User Representations File (Exemplary)**:
 
 ![Generate ServiceCutter SCL File](/img/service-cutter-input-generation-2.png)
 
-**Note:** The generated SCL file is a template which helps you by giving the structure. The following generated parts are only examples and have to be adjusted:
+**Note:** The generated SCL file is a template that intends to help you by setting the structure expected by Service Cutter. The following generated parts are only examples, and will have to be adjusted:
 
  * **Use Cases**
- * **All Compatibilities**
+ * **All [Compatibilities](https://github.com/ServiceCutter/ServiceCutter/wiki/Compatibilities)**
  * **Security Access Groups**
  * **Separated Security Zone**
  * **Shared Owner Group**
 
-Only the following elements are actually derived from your CML model and don't have to be changed:
+The following elements are actually derived from the CML model and do not have to be changed:
 
  * **Aggregates** (derived from your Aggregates in the CML file)
  * **PredefinedService** (derived from your bounded contexts in the CML file)
 
+ 
+
 ### Generate User Representations JSON File
 Once you have prepared your SCL file, you can generate the corresponding JSON file with the action **Service Cutter: Generate User Representations File (JSON)** in the context menu:
 
 ![Generate ServiceCutter JSON out of SCL File](/img/service-cutter-input-generation-3.png)
 
 ### Using the JSON files in Service Cutter
-You have now both JSON files needed for the Service Cutter tool, generated into the **src-gen** folder:
+Now you have both JSON files that are required for the Service Cutter tool, generated into the **src-gen** folder:
 
 ![Generated JSON files for Service Cutter](/img/service-cutter-input-generation-4.png)
 
 Have fun with cutting your services :)
 
+*Note:* Service Cutter has not been updated in a while, and only intended to demonstrate the possibilities of criteria-based graph clustering in the context of service decomposition (and establish a method and a first catalog of criteria). So do not expect mature, production-ready cuts to be suggested, but view them as a discussion and design workshop input. Further research is required to harden the approach; such research is ongoing (evidence: [40+ citations of the Service Cutter paper presented at ESOCC 2016](https://www.researchgate.net/publication/307873263_Service_Cutter_A_Systematic_Approach_to_Service_Decomposition)).  
+
 ![Service Cutter Insurance Example](/img/service-cutter-insurance-example.png)
 
 
diff --git a/_docs/language-reference/imports.md b/_docs/language-reference/imports.md
index 52f71de..b56cd0f 100644
--- a/_docs/language-reference/imports.md
+++ b/_docs/language-reference/imports.md
@@ -3,8 +3,8 @@ title: Imports
 permalink: /docs/imports/
 ---
 
-CML models can be divided into multiple *.cml files. For example, you may want to specify Bounded Contexts in separate files and use them in multiple Context Maps.
-One *.cml file can only contain one Context Map. However, multiple Context Maps in separate *.cml files can import the same files describing the Bounded Contexts.
+CML models can be divided into multiple `*.cml` files. For example, you may want to specify Bounded Contexts in separate files and use them in multiple Context Maps.
+One `*.cml` file can only contain one Context Map. However, multiple Context Maps in separate `*.cml` files can import the same files describing the Bounded Contexts.
 
 ## Example
 
@@ -63,7 +63,7 @@ A file containing the ContextMap can then import the Bounded Contexts with the *
 }
 

 
-It is also possible to import *.cml files located in other directories:
+It is also possible to import `*.cml` files located in other directories:
 
 
import "./BoundedContexts/CustomerManagement.cml"
 import "./BoundedContexts/PolicyManagement.cml"
@@ -80,6 +80,5 @@ It is also possible to import *.cml files located in other directories:
 

 
 

-Note: Although you can import *.cml files from different directories our Eclipse IDE plugin will only be able to resolve files 
-within the same Eclipse project.
+Note: Although you can import *.cml files from different directories, our Eclipse plugin will only be able to resolve files within the same Eclipse project.
 

diff --git a/_docs/tutorials/event-sourcing-and-cqrs-modeling.md b/_docs/tutorials/event-sourcing-and-cqrs-modeling.md
index 2896d8d..03c0365 100644
--- a/_docs/tutorials/event-sourcing-and-cqrs-modeling.md
+++ b/_docs/tutorials/event-sourcing-and-cqrs-modeling.md
@@ -20,9 +20,9 @@ If you are not fully familiar with the concepts of event sourcing and CQRS yet,
 ## Tutorial
 
 ### Context and Objectives 
-This tutorial highlights the [Context Mapper DSL (CML)](/docs/language-reference/) concepts that support modeling event-sourced systems and CQRS. 
+This tutorial highlights the [Context Mapper DSL (CML)](/docs/language-reference/) concepts that support a) modeling event-sourced systems and b) CQRS. 
 
-Within CML Bounded Contexts and Aggregates, we integrated the [Sculptor DSL for tactic DDD](http://sculptorgenerator.org/) that allows domain-driven designers to specify the domain model of Bounded Contexts.
+Within CML Bounded Contexts and Aggregates, we integrated the [Sculptor DSL for tactic DDD](http://sculptorgenerator.org/) that allows domain-driven designers to specify the domain model of Bounded Contexts. This tutorial features this DSL.
 
 ### Events
 As explained in the [Sculptor documentation](http://sculptorgenerator.org/documentation/event-driven-tutorial), the syntax of Sculptor supports modeling events.

From 556231d5a4d46bb8c4792c04c9ea45511884aa52 Mon Sep 17 00:00:00 2001
From: Zimmermann Olaf 
Date: Mon, 23 Mar 2020 20:39:33 +0100
Subject: [PATCH 7/9] Updating code snippets to match e2e example

---
 .../event-sourcing-and-cqrs-modeling.md       | 101 +++++++++++++-----
 1 file changed, 74 insertions(+), 27 deletions(-)

diff --git a/_docs/tutorials/event-sourcing-and-cqrs-modeling.md b/_docs/tutorials/event-sourcing-and-cqrs-modeling.md
index 03c0365..9fc6bb0 100644
--- a/_docs/tutorials/event-sourcing-and-cqrs-modeling.md
+++ b/_docs/tutorials/event-sourcing-and-cqrs-modeling.md
@@ -10,9 +10,9 @@ CQRS separates query processing from the create, update, delete business logic s
 If you are not fully familiar with the concepts of event sourcing and CQRS yet, you may find the following resources helpful:
 
  * [Event sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) by Martin Fowler
- * [CQRS and Event Sourcing (Video)](https://www.youtube.com/watch?v=JHGkaShoyNs) by Greg Young
- * [Event sourcing pattern](https://microservices.io/patterns/data/event-sourcing.html) by Chris Richardson
  * [Event sourcing workshop slides](https://speakerdeck.com/mploed/event-sourcing-workshop-at-software-architecture-summit-2016) by Michael Plöd
+ * [Event sourcing pattern](https://microservices.io/patterns/data/event-sourcing.html) by Chris Richardson
+  * [CQRS and Event Sourcing (Video)](https://www.youtube.com/watch?v=JHGkaShoyNs) by Greg Young
  * [Command query separation](https://martinfowler.com/bliki/CommandQuerySeparation.html) and [CQRS](https://martinfowler.com/bliki/CQRS.html) by Martin Fowler
  * [Developing Transactional Microservices Using Aggregates, Event Sourcing and CQRS](https://www.infoq.com/articles/microservices-aggregates-events-cqrs-part-1-richardson/) by Chris Richardson
  * [Designing Event Sourced Microservices](https://www.infoq.com/news/2017/11/event-sourcing-microservices/) by Jan Stenberg
@@ -20,7 +20,7 @@ If you are not fully familiar with the concepts of event sourcing and CQRS yet,
 ## Tutorial
 
 ### Context and Objectives 
-This tutorial highlights the [Context Mapper DSL (CML)](/docs/language-reference/) concepts that support a) modeling event-sourced systems and b) CQRS. 
+This tutorial highlights the [Context Mapper DSL (CML)](/docs/language-reference/) concepts that support a) modeling event-sourced systems and b) applying the CQRS pattern. 
 
 Within CML Bounded Contexts and Aggregates, we integrated the [Sculptor DSL for tactic DDD](http://sculptorgenerator.org/) that allows domain-driven designers to specify the domain model of Bounded Contexts. This tutorial features this DSL.
 
@@ -32,6 +32,8 @@ suggests that the scope of domain events should always be based on Aggregates. T
 
 The following example illustrates how you can model domain events within your Aggregate: 
 
+
+
 ```text
 abstract DomainEvent AbstractDomainEvent {
   Date timestamp
@@ -43,7 +45,13 @@ DomainEvent CustomerVerifiedEvent extends AbstractDomainEvent {
 
 DomainEvent AddressUpdatedEvent extends AbstractDomainEvent {
   - CustomerId customer  
-  - AddressId address
+  - AddressDto address
+}
+
+ValueObject AddressDto {
+	String streetAddress
+	String city
+	String postalCode
 }
 ```
 
@@ -51,7 +59,7 @@ You can also reference your events in services, repositories, or any other tacti
 
 ```text
 Service AddressService {
-  @AddressUpdatedEvent updateAddress(@AddressId address);
+  @AddressUpdatedEvent updateAddress(@AddressDto address);
 }
 ```
 
@@ -64,13 +72,21 @@ Applying CQRS to a Bounded Context definition in Context Mapper can be expressed
 #### Step 1: Separating Queries and Commands
 Here is an example of a conventional service interface that exposes both create, read, update, delete, and search methods/operations:
 
+
+
 ```text
+ValueObject CustomerDto {
+	String customerId
+	CustomerProfileDto customerProfile
+	List links
+}
+
 Service CustomerService {
-  @CustomerId createCustomer(@Customer customer);
-  void updateCustomer(@Customer customer);
+  @CustomerId createCustomer(@CustomerDTO customer);
+  void updateCustomer(@CustomerDTO customer);
   boolean deleteCustomer(@CustomerId customer);
-  @Customer findCustomerById(@CustomerId customerId);
-  List<@Customer> findCustomersByName(String name);
+  @CustomerDTO findCustomerById(@CustomerId customerId);
+  List<@CustomerDTO> findCustomersByName(String name);
 }
 ```
 
@@ -78,31 +94,38 @@ You can CQRS-ify the above interface by splitting it into two service interfaces
 
 ```text
 Service CustomerCommandService {
-  @CustomerId createCustomer(@Customer customer);
-  void updateCustomer(@Customer customer);
+  @CustomerId createCustomer(@CustomerDTO customer);
+  void updateCustomer(@CustomerDTO customer);
   boolean deleteCustomer(@CustomerId customer);
 }
 
 Service CustomerQueryService {
-  @Customer findCustomerById(@CustomerId customerId);
-  List<@Customer> findCustomersByName(String name);
+  @CustomerDTO findCustomerById(@CustomerId customerId);
+  List<@CustomerDTO> findCustomersByName(String name);
 }
 ```
 
 Additionally, Sculptor introduces so-called *command events* to support CQRS explicitly (described [here](http://sculptorgenerator.org/documentation/event-driven-tutorial#commandevent)).
 In comparison to a domain event which describes something that has happened, a command event is something that the system is asked to perform. The following CML/Sculptor snippet illustrates an example how to model command events:
 
+
+```text
+		CommandEvent RecordAddressChange {
+ 			 -AddressDto newAddress
+ 			 Date changeDate
+		}	
+```
+
 ```text
 CommmandEvent RecordShipmentArrival {
   - ShipmentId shipment
   Date arrivalDate
 }
 ```
+-->
 
 #### Step 2: Separating Read and Command Models
-In a second step you may want to define completely different models for read and command access. At present, the Context Mapper DSL does not 
-have any specific language construct for read models; we suggest that you use the Michael's Aggregate rule from above to specify read models. 
-The following example illustrates how you could model your Aggregate (command model) and your read model:
+In a second step you may want to define completely different models for read and command access. At present, the Context Mapper DSL does not have any specific language construct for read models; we suggest that you use the Michael's Aggregate rule from above to specify read models. The following example illustrates how you could model your Aggregate (command model) and your read model:
 
 ```text
 Aggregate CustomerAggregate {
@@ -110,20 +133,11 @@ Aggregate CustomerAggregate {
     UUID uniqueCustomerId
   }
 
-  Entity Customer {
-    aggregateRoot
-
-    CustomerId customerId
-    String firstName
-    String lastName
-    List
 addresses
-  }
- 
   Entity Address // not designed in detail 
 
   Service CustomerCommandService {
-    @CustomerId createCustomer(@Customer customer);
-    void updateCustomer(@Customer customer);
+    @CustomerId createCustomer(@CustomerDTO customer);
+    void updateCustomer(@CustomerDTO customer);
     boolean deleteCustomer(@CustomerId customer);
   }
 }
@@ -152,6 +166,39 @@ The [Sculptor generator](http://sculptorgenerator.org) further supports event so
 However, the DSL syntax itself does not need additional concepts to support it. It is based on the _DomainEvents_, _Repositories_, and _Services_ provided by the Sculptor and also CML.
   * *Note:* We only used the Sculptor syntax for the tactic DDD grammar of our CML language. Using the Sculptor generator in Context Mapper is currently not supported.
 
+
+
+
 ## Other Tutorials and Links
  * Tutorial: [Document Event Storming Results with Context Mapper](/docs/event-storming/)
  * Presentation on Context Mapper: [Context Mapper: DSL and Tools for Domain-Driven Service Design - Bounded Context Modeling and Microservice Decomposition](https://contextmapper.org/media/ZIOSK-ContextMapper4JUGv10p.pdf)

From f43dc470c2130f9dcf5c30c391ff24a0dc273e5e Mon Sep 17 00:00:00 2001
From: Stefan Kapferer 
Date: Thu, 26 Mar 2020 11:49:14 +0100
Subject: [PATCH 8/9] Fix merge errors

---
 _docs/generators/generators.md                   | 6 ++++--
 _docs/generators/generic-freemarker-generator.md | 2 --
 _docs/getting-started.md                         | 2 --
 _docs/language-reference/bounded-context.md      | 2 +-
 4 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/_docs/generators/generators.md b/_docs/generators/generators.md
index 82baa74..689675e 100644
--- a/_docs/generators/generators.md
+++ b/_docs/generators/generators.md
@@ -3,8 +3,10 @@ title: Generators Overview
 permalink: /docs/generators/
 ---
 
-The Context Mapper generators provide transformations to derive graphical Context Maps, [PlantUML diagrams](http://plantuml.com/), [Microservice Domain-Specific Langauge (MDSL)](https://socadk.github.io/MDSL/) (micro-)service contracts, and 
-[Service Cutter](https://servicecutter.github.io/) input files from your CML context map. We also provide a [generic, template-based generator](/docs/generic-freemarker-generator/) based on Freemarker which allows to generate arbitrary textual files.
+The Context Mapper generators provide transformations to derive graphical Context Maps, [PlantUML diagrams](http://plantuml.com/), 
+[Microservice Domain-Specific Langauge (MDSL)](https://socadk.github.io/MDSL/) (micro-)service contracts, and 
+[Service Cutter](https://servicecutter.github.io/) input files from your CML context map. We also provide a [generic, template-based generator](/docs/generic-freemarker-generator/) 
+based on Freemarker which allows to generate arbitrary textual files.
 
 **Generators:**
  * [Graphical context maps](#graphical-context-maps)
diff --git a/_docs/generators/generic-freemarker-generator.md b/_docs/generators/generic-freemarker-generator.md
index e71b985..25b128c 100644
--- a/_docs/generators/generic-freemarker-generator.md
+++ b/_docs/generators/generic-freemarker-generator.md
@@ -157,8 +157,6 @@ relationship
       +- name = "INFLUENCER"
 ```
 
-
-
 #### Relationship Type Checking
 To respect the different structures when processing the relationship list, we provide a method that allows you to check the type of the relationship:
 
diff --git a/_docs/getting-started.md b/_docs/getting-started.md
index ebcde34..0184d40 100644
--- a/_docs/getting-started.md
+++ b/_docs/getting-started.md
@@ -56,8 +56,6 @@ The following example gives you a first impression how CML context maps look lik
 }
- - The bounded contexts have to be specified before you can use them within a context map. A simple example of a bounded context definition is: diff --git a/_docs/language-reference/bounded-context.md b/_docs/language-reference/bounded-context.md index e72f18c..d04eb24 100644 --- a/_docs/language-reference/bounded-context.md +++ b/_docs/language-reference/bounded-context.md @@ -57,7 +57,7 @@ The example above also shows how you can let one bounded context refine another All of the following attributes are **optional** and you do not have to specify them all. ### Bounded Context Type -With the _type_ keyword you define the bounded contexts type, which can be one of the following: +With the _type_ keyword you define the bounded contexts type, which can be one of the following: * FEATURE * APPLICATION From 29f8b333f9fd36c9e32a754c2600c70bffd36b73 Mon Sep 17 00:00:00 2001 From: Stefan Kapferer Date: Thu, 26 Mar 2020 12:02:22 +0100 Subject: [PATCH 9/9] Some fixes and corrections --- .../event-sourcing-and-cqrs-modeling.md | 32 +++++++------------ 1 file changed, 11 insertions(+), 21 deletions(-) diff --git a/_docs/tutorials/event-sourcing-and-cqrs-modeling.md b/_docs/tutorials/event-sourcing-and-cqrs-modeling.md index b3a960e..1aabff8 100644 --- a/_docs/tutorials/event-sourcing-and-cqrs-modeling.md +++ b/_docs/tutorials/event-sourcing-and-cqrs-modeling.md @@ -12,7 +12,7 @@ If you are not fully familiar with the concepts of event sourcing and CQRS yet, * [Event sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) by Martin Fowler * [Event sourcing workshop slides](https://speakerdeck.com/mploed/event-sourcing-workshop-at-software-architecture-summit-2016) by Michael Plöd * [Event sourcing pattern](https://microservices.io/patterns/data/event-sourcing.html) by Chris Richardson - * [CQRS and Event Sourcing (Video)](https://www.youtube.com/watch?v=JHGkaShoyNs) by Greg Young + * [CQRS and Event Sourcing (Video)](https://www.youtube.com/watch?v=JHGkaShoyNs) by Greg Young * [Command query separation](https://martinfowler.com/bliki/CommandQuerySeparation.html) and [CQRS](https://martinfowler.com/bliki/CQRS.html) by Martin Fowler * [Developing Transactional Microservices Using Aggregates, Event Sourcing and CQRS](https://www.infoq.com/articles/microservices-aggregates-events-cqrs-part-1-richardson/) by Chris Richardson * [Designing Event Sourced Microservices](https://www.infoq.com/news/2017/11/event-sourcing-microservices/) by Jan Stenberg @@ -63,7 +63,8 @@ Service AddressService { ``` ### CQRS Example -Applying CQRS to a Bounded Context definition in Context Mapper can be expressed with the standard language constructs of Context Mapper and Sculptor: you can simply apply this architectural pattern by +Applying CQRS to a Bounded Context definition in Context Mapper can be expressed with the standard language constructs of Context Mapper and Sculptor: you can simply apply +this architectural pattern by 1. Separating the queries from the command methods and defining separate services 2. Defining separate command and query models @@ -71,13 +72,11 @@ Applying CQRS to a Bounded Context definition in Context Mapper can be expressed #### Step 1: Separating Queries and Commands Here is an example of a conventional service interface that exposes both create, read, update, delete, and search methods/operations: - - ```text -ValueObject CustomerDto { - String customerId - CustomerProfileDto customerProfile - List links +ValueObject CustomerDTO { + String customerId + CustomerProfileDto customerProfile + List links } Service CustomerService { @@ -107,21 +106,12 @@ Service CustomerQueryService { Additionally, Sculptor introduces so-called *command events* to support CQRS explicitly (described [here](http://sculptorgenerator.org/documentation/event-driven-tutorial#commandevent)). In comparison to a domain event which describes something that has happened, a command event is something that the system is asked to perform. The following CML/Sculptor snippet illustrates an example how to model command events: - ```text - CommandEvent RecordAddressChange { - -AddressDto newAddress - Date changeDate - } +CommandEvent RecordAddressChange { + -AddressDto newAddress + Date changeDate +} ``` - -```text -CommmandEvent RecordShipmentArrival { - - ShipmentId shipment - Date arrivalDate -} -``` ---> #### Step 2: Separating Read and Command Models In a second step you may want to define completely different models for read and command access. At present, the Context Mapper DSL does not have any specific language construct for read models; we suggest that you use the Michael's Aggregate rule from above to specify read models. The following example illustrates how you could model your Aggregate (command model) and your read model: