docs: improve documentation

Improved the wording in the text.
Do minor restructuring of content.

Relates to: MODELIX-869

docs/global/modules/samples/pages/use_case_2.adoc

@@ -2,18 +2,22 @@
 :navtitle: 2. Model server and web frontend
 
 This use case realizes the synchronization of model data between two web frontends and a model server.
+Optionally, an MPS project can be run and also synchronize its model data with the model server.
 
-One web frontend is the *Management application* implemented in https://vuejs.org/[Vue.js] and can modify the model content.
+One web frontend is the *Management application* implemented in Vue.js.
+It can be used to edit the model content.
 It uses the https://artifacts.itemis.cloud/service/rest/repository/browse/npm-open/%40modelix/model-client/[@modelix/model-client], the https://artifacts.itemis.cloud/service/rest/repository/browse/npm-open/%40modelix/vue-model-api/[@modelix/vue-model-api] and code generated by the  xref:core:reference/component-model-api-gen-gradle.adoc[Model API generator].
 The generated code provides type-safe access to model data and is derived from the xref:metamodel.adoc[MPS languages under `mps/languages`].
 
-The other web frontend is written in https://angular.io/[Angular] and only reads model data. It also uses the `model-client` and the generated type-safe TypeScript API.
+The other web frontend is the *Overview application* and is implemented in Angular.
+It displays an overview of model data.
+It also uses the `model-client` and the generated type-safe TypeScript API.
 
-A running MPS instance can also sync model data using the https://artifacts.itemis.cloud/service/rest/repository/browse/maven-mps/org/modelix/mps/model-server-sync-plugin/[model-server-sync-plugin].
+A running MPS projects syncs model data using the https://artifacts.itemis.cloud/service/rest/repository/browse/maven-mps/org/modelix/mps/model-server-sync-plugin/[model-server-sync-plugin].
 
 NOTE: The web frontends communicate directly with a model server and not through an intermediary custom backend like in xref:overview.adoc#use_case_3[use case 3].
 
-NOTE: Take a look at the xref:overview.adoc[overview] to understand how this use case relates to the other use cases
+NOTE: Take a look at the xref:overview.adoc[overview] to understand how this use case relates to the other use cases.
 
 == Demonstration
 
@@ -28,53 +32,60 @@ image::use_case_2_sequence.svg[Static,1920]
 // Mermaid source. Edit with https://mermaid.live/
 // sequenceDiagram
 //     actor back-office
-//     actor tutor
 //     actor student
+//     actor tutor
 //     tutor->>Management application: make change
 //     Management application-->>tutor: display change
-//     Management application->>Model server: communicate change
+//     Management application->>Model server: propagate change
 //     Model server-->>Management application:
-//     Model server->>Overview application: communicate change
+//     Model server->>Overview application: propagate change
 //     Overview application-->>Model server:
 //     Overview application-->>student: display change
-//     Model server->>MPS: communicate change
+//     Model server->>MPS: propagate change
 //     MPS-->>Model server:
 //     MPS-->>back-office: display change
 //     back-office->>MPS: make change
 //     MPS-->>back-office: display change
-//     MPS->>Model server: communicate change
+//     MPS->>Model server: propagate change
 //     Model server-->>MPS:
-//     Model server->>Overview application: communicate change
+//     Model server->>Overview application: propagate change
 //     Overview application-->>Model server:
 //     Overview application-->>student: display change
-//     Model server->>Management application: communicate change
+//     Model server->>Management application: propagate change
 //     Management application-->>Model server:
 //     Management application-->>tutor: display change
 
-== Build
+In this demonstration
+
+1. Model data is edited through the *Management application*.
+2. Those changes are then synced to the *Overview application* and MPS through the model server.
+3. Model data is edited again in MPS by reverting the made changes.
+4. Those changes are then also synced back.
+
+== Instructions
+
+You can try the demo yourself by downloading the https://github.com/modelix/modelix.samples/[samples repository].
 
-Use Gradle to build the relevant components.
+In the downloaded repository, use Gradle to build the relevant components.
 
 .Command to build needed components
 [source,shell]
 ----
 ./gradlew spa-management-vue:build spa-overview-angular:build mps:project-modelserver-backend:build
 ----
 
-This command:
+This command
 
-* Install dependencies in the MPS project `mps/project-modelserver-backend`
+* Installs dependencies in the MPS project `mps/project-modelserver-backend`.
 +
 The main dependency is the https://artifacts.itemis.cloud/service/rest/repository/browse/maven-mps/org/modelix/mps/model-server-sync-plugin/[model-server-sync-plugin].
-* Generates TypeScript sources in `mps/metamodel-api-ts`
+* Generates TypeScript sources in `mps/metamodel-api-ts`.
 +
 Those sources are  generated from the xref:metamodel.adoc[MPS languages] in `mps/languages`.
 They are used in the `spa-management-vue` and `spa-overview-angular`.
-* builds the Single-page applications `spa-management-vue` and `spa-overview-angular`
+* Builds the Single-page applications `spa-management-vue` and `spa-overview-angular`.
 
-== Start
-
-Start up the components.
+Start the components:
 
 [source,shell]
 ----
@@ -84,21 +95,13 @@ docker-compose --profile useCase2 up
 This starts:
 
 * a xref:core:reference/component-model-server.adoc[model server] with initial data under http://localhost:28101/
-* the *Management application* under http://localhost:3000/
-* the *Overview application* under http://localhost:4200/
+* the *Management application* at http://localhost:3000/
+* the *Overview application* at http://localhost:4200/
 
 === MPS (optionally)
 
-Start MPS `2021.2.6`  without any global plugins and open the project in the `mps/project-mps-backend` folder.
+Start MPS 2021.2.6  without any global plugins and open the project in the `mps/project-mps-backend` folder.
 
 This MPS project has a plugin installed and configured to sync the model content automatically with the model server.
 
 xref:use_case_1.adoc[Use case 1] describes the synchronization between a model client and an MPS instance.
-
-== Use
-
-Now you can modify the model through the *Management application*.
-Those changes are first synced to the model server.
-The model server syncs those changes to other opened web applications, like the *Overview application* or other instances of the *Management application* open in another tab.
-
-If you have an MPS instance running and connected to the model server, changes made in MPS are synced with web applications, and vice versa.

docs/global/modules/samples/pages/use_case_3.adoc

@@ -40,8 +40,8 @@ image::use_case_3_sequence.svg[Static,1920]
 
 // sequenceDiagram
 //     actor back-office
-//     actor tutor
 //     actor student
+//     actor tutor
 //     participant Dashboard frontend (tutor)
 //     participant Dashboard frontend (student)
 //     participant Dashboard backend
@@ -50,30 +50,44 @@ image::use_case_3_sequence.svg[Static,1920]
 //
 //     tutor->>Dashboard frontend (tutor): make change
 //     Dashboard frontend (tutor)-->>tutor: display change
-//     Dashboard frontend (tutor)->>Dashboard backend: communicate change
-//     Dashboard backend->>Model server: communicate change
+//     Dashboard frontend (tutor)->>Dashboard backend: propagate change
+//     Dashboard backend->>Model server: propagate change
 //     Model server-->>Dashboard backend:
 //     Dashboard backend-->>Dashboard frontend (tutor):
-//     Dashboard backend->>Dashboard frontend (student): communicate change
+//     Dashboard backend->>Dashboard frontend (student): propagate change
 //     Dashboard frontend (student)-->>student: display change
-//     Model server->>MPS: communicate change
+//     Model server->>MPS: propagate change
 //     MPS-->>Model server:
 //     MPS-->>back-office: display change
 //
 //     back-office->>MPS: make change
 //     MPS-->>back-office: display change
-//     MPS->>Model server: communicate change
+//     MPS->>Model server: propagate change
 //     Model server-->>MPS:
-//     Model server->>Dashboard backend: communicate change
+//     Model server->>Dashboard backend: propagate change
 //     Dashboard backend-->>Model server:
-//     Dashboard backend->>Dashboard frontend (tutor): communicate change
+//     Dashboard backend->>Dashboard frontend (tutor): propagate change
 //     Dashboard frontend (tutor)-->>tutor: display change
-//     Dashboard backend->>Dashboard frontend (student): communicate change
-//     Dashboard frontend (student)-->>tutor: display change
+//     Dashboard backend->>Dashboard frontend (student): propagate change
+//     Dashboard frontend (student)-->>student: display change
+
+In this demonstration
+
+1. Data is changed in one of the opened web frontends.
+2. These changes are first propagated to the web backend.
+3. The web backend propagates the changes to the model server.
+4. The web backend also propagates the changes to the other opened web frontend.
+5. The model server syncs the changes into MPS.
+6. Model data is edited again in MPS by reverting the made changes.
+7. Those changes are then also propagated to the model server.
+8. The model server propagates the changes to the web backend.
+9. The web backend propagates the changes to all opened web frontends.
 
-== Build
+== Instructions
 
-Use Gradle to build the relevant components.
+You can try the demo yourself by downloading the https://github.com/modelix/modelix.samples/[samples repository].
+
+In the downloaded repository, use Gradle to build the relevant components.
 
 .Command to build the needed components
 [source,shell]
@@ -93,20 +107,18 @@ They are used in the `spa-management-vue` and `spa-overview-angular`.
 * builds the web backend `rest-api-model-server`
 * builds the web frontend `spa-dashboard-angular`
 
-== Start
-
-Start up the components.
+Start the components:
 
 [source,shell]
 ----
 docker-compose --profile useCase3 up
 ----
 
-This starts:
+This starts
 
 * a xref:core:reference/component-model-server.adoc[model server] with initial data under http://localhost:28101/
-* the *web backend* under http://localhost:8090/
-* the *web frontend* under http://localhost:4201/
+* the *web backend* at http://localhost:8090/
+* the *web frontend* at http://localhost:4201/
 
 === MPS (optionally)
 
@@ -116,15 +128,7 @@ This MPS project has a plugin installed and configured to sync the model content
 
 xref:use_case_1.adoc[Use case 1] describes the synchronization between a model client and an MPS instance.
 
-== Use
-
-Now you can modify the model through the web frontend.
-Those changes are first communicated to the web backend.
-From there, they are communicated to the model server.
-
-The model server syncs those changes to other open web applications. You can see this by opening the dashboard a second time in a different tab.
-
-If you have an MPS instance running and connected to the model server, changes made in MPS are synced with web applications, and vice versa.
+=== Web frontends from use case 2 (optionally)
 
 You can also start the web frontends from xref:use_case_2.adoc[use case 2]
-and see how changes to the model are propagated there.
+and see how changes to the model are propagated there.