Update and fix the documentation

documentation/ame-guide/modules/ROOT/nav.adoc

@@ -21,10 +21,12 @@
 ***  xref:modeling/trait.adoc[]
 ***  xref:modeling/operation.adoc[]
 ***  xref:modeling/event.adoc[]
+** xref:modeling/connect-elements.adoc[]
 ** xref:modeling/shared-models.adoc[]
 ** xref:modeling/migration-of-models.adoc[]
 ** xref:modeling/model-versions.adoc[Aspect Model versions]
 * xref:namespace/namespaces-references.adoc[]
+** xref:namespace/workspace.adoc[]
 ** xref:namespace/import-namespaces.adoc[]
 ** xref:namespace/export-namespaces.adoc[]
 ** xref:namespace/use-external-references.adoc[]

documentation/ame-guide/modules/ROOT/pages/getting-started/edit-models.adoc

@@ -88,18 +88,10 @@ Use the following advanced search possibilities for more specific search results
 [[connecting-elements]]
 == Connect elements
 
-In some situations you might want to connect elements manually, e.g., when you want to reuse a Characteristic and connect a second Property to it.
+In some situations you might want to connect elements manually, e.g., when you want to reuse a Characteristic
+and connect a second Property to it.
 
-To connect two elements manually, proceed as follows:
-
-. Click both elements while holding the CTRL key on your keyboard.
-. Click the *Connect* icon in the xref:getting-started/ui-overview.adoc#toolbar[toolbar].
-+
-image::connecting-elements.png[width=100%]
-
-→ Both elements are now connected.
-
-Tip: Alternatively, you can use the context menu (right mouse click) to access the action items.
+Find details on the various options on how to create the connection at xref:modeling/connect-elements.adoc[].
 
 
 == Delete elements

documentation/ame-guide/modules/ROOT/pages/getting-started/ui-overview.adoc

@@ -1,5 +1,3 @@
-:page-partial:
-
 [[aspect-model-editor-ui-overview]]
 = Aspect Model Editor UI overview
 
@@ -10,14 +8,15 @@ image::ame-ui-overview-numbers.png[Numbered UI overview, width=100%]
 The numbers in the image above indicate the following UI elements of the Aspect Model Editor:
 
 1. xref:getting-started/ui-overview.adoc#toolbar[Toolbar]
-2. xref:getting-started/ui-overview.adoc#settings[Settings]
-3. xref:getting-started/ui-overview.adoc#notifications[Notifications]
-4. xref:getting-started/ui-overview.adoc#workspace-sidebar[Workspace sidebar]
-5. xref:getting-started/ui-overview.adoc#map[Map]
-6. xref:getting-started/ui-overview.adoc#edit-dialog[Edit dialog]
-7. xref:getting-started/ui-overview.adoc#add-icon[Add icon]
-8. xref:getting-started/ui-overview.adoc#navigation[Navigation]
-9. xref:getting-started/ui-overview.adoc#search[Search]
+2. xref:getting-started/ui-overview.adoc#map[Map]
+3. xref:getting-started/ui-overview.adoc#navigation[Navigation]
+4. xref:getting-started/ui-overview.adoc#search[Search]
+5. xref:getting-started/ui-overview.adoc#settings[Settings]
+6. xref:getting-started/ui-overview.adoc#notifications[Notifications]
+7. xref:getting-started/ui-overview.adoc#help[Help]
+8. xref:getting-started/ui-overview.adoc#workspace-sidebar[Workspace sidebar]
+9. xref:getting-started/ui-overview.adoc#edit-dialog[Edit dialog]
+
 
 [[toolbar]]
 == Toolbar
@@ -107,65 +106,57 @@ For more information, see xref:getting-started/validation-and-notifications.adoc
 
 |===
 
-[[workspace-sidebar]]
-== Workspace sidebar
 
-The Workspace sidebar – see screenshot below – allows you to access namespaces (1) and to drag and drop elements to the graph area canvas (2). 
+[[map]]
+== Map
 
-image::ame-ui-overview-workspace-numbers.png[width=100%]
+With the map, you can easily navigate your Aspect Model in the graph area canvas.
 
-Expand the Workspace sidebar to view the description of each element.
+To toggle its visibility, click the Show/Hide map icon image:toolbar-icons/minimap.png[Map toggle icon] in the toolbar.
 
-To add an element to your model drag and drop it on the graph area canvas, edit its details, and connect it with the rest of the graph.
+For more information, see xref:getting-started/navigate-models.adoc[Navigate models].
 
-For more information, see xref:getting-started/edit-models.adoc[Edit models].
+[[navigation]]
+== Navigation
 
-[[map]]
-== Map
+Optimize your current view of the model with the navigation:
 
-With the map, you can easily navigate your Aspect Model in the graph area canvas. 
+* Fit the complete model on the current view
+* Reset zoom level to 100%
+* Zoom in
+* Zoom out
 
-To toggle its visibility, click the Show/Hide map icon image:toolbar-icons/minimap.png[Map toggle icon] in the toolbar.
+image:zoom-fit.png[]
 
 For more information, see xref:getting-started/navigate-models.adoc[Navigate models].
 
-[[edit-dialog]]
-== Edit dialog
+[[help]]
+== Help
 
-Edit the attributes of a selected element of your Aspect Model with the Edit dialog.
-
-To access the details of an element in the Edit dialog, either double-click the element or select the element and click the Edit icon image:toolbar-icons/edit.png[Edit icon] on the xref:getting-started/ui-overview.adoc#toolbar[toolbar].
+The help icon image:toolbar-icons/info.png[] opens a page which lists details about the application and provides
+a link to the documentation.
 
-For more information, see xref:modeling/edit-elements.adoc[Edit elements].
+Example:
+image:help-docs.png[]
 
-[[add-icon]]
-== Add icon
+[[workspace-sidebar]]
+== Workspace sidebar
 
-Add the next logical element with the Add icon image:add.png[Add icon].
+The Workspace sidebar – see screenshot below – allows you to access namespaces (1) and to drag and drop elements to the graph area canvas (2).
 
-For example, the Add icon at the top of a Characteristic element creates a Trait connected to:
-* The parent Property
-* An existing Characteristic
-* A new Constraint
+image::ame-ui-overview-workspace-numbers.png[width=100%]
 
-For more information, see xref:getting-started/edit-models.adoc#adding-elements[Use the Add icon].
+Expand the Workspace sidebar to view the description of each element.
 
-[[navigation]]
-== Navigation
+To add an element to your model drag and drop it on the graph area canvas, edit its details, and connect it with the rest of the graph.
 
-Optimize your current view of the model with the navigation:
+For more information, see xref:getting-started/edit-models.adoc[Edit models].
 
-* Fit the complete model on the current view
-* Reset zoom level to 100%
-* Zoom in
-* Zoom out
+[[edit-dialog]]
+== Edit dialog
 
-image::zoom-fit.png[Zoom icons, width=100%]
+Edit the attributes of a selected element of your Aspect Model with the Edit dialog.
 
-For more information, see xref:getting-started/navigate-models.adoc[Navigate models].
+To access the details of an element in the Edit dialog, either double-click the element or select the element and click the Edit icon image:toolbar-icons/edit.png[Edit icon] on the xref:getting-started/ui-overview.adoc#toolbar[toolbar].
 
-++++
-<style>
-  .imageblock {flex-direction: row !important;}
-</style>
-++++
+For more information, see xref:modeling/edit-elements.adoc[Edit elements].

documentation/ame-guide/modules/ROOT/pages/modeling/connect-elements.adoc

@@ -0,0 +1,40 @@
+= Connect elements
+
+The elements of an Aspect Model – such as Properties, Operations, Characteristics, Constraints, Entities, or Events –
+can be distributed over the complete editor main canvas.
+
+To connect two elements manually, proceed as follows:
+
+. Click both elements while holding the CTRL key on your keyboard.
+. Click the *Connect* icon in the xref:getting-started/ui-overview.adoc#toolbar[toolbar].
++
+image::connecting-elements.png[width=100%]
+
+→ Both elements are now connected.
+
+* If only one direction is permitted, the arrow will be set respectively.
+* If both directions are permitted, the arrow will be set for the element selected first to the element selected second.
+* Tf a connection is not permitted, a respective warning will appear and the elements will not be connected.
+
+TIP: Alternatively, you can use the context menu (right mouse click) to access the action items.
+
+The larger the diagram, the harder it might get elements that are fare away.
+
+In case you cannot connect two elements just the way you are most familiar with, try one of these procedures.
+
+== Connect via context menu
+
+* Click the source element.
+* Right-click to access the context menu.
+* Select *connect with ...*.
+* The new pop-up displays all the elements of the model. +
+  In case there are too element many type the name in the search field.
+* Select the target element.
+* Click *Connect* to confirm.
+
+Upon success the arrow is visible.
+In case you try to connect elements which cannot be connected, a validation notification will inform you respectively.
+
+== Connect via focus
+
+* Single click the first element - this sets focus on element

documentation/ame-guide/modules/ROOT/pages/modeling/migration-of-models.adoc

@@ -1,5 +1,3 @@
-:page-partial:
-
 [[migration-of-models]]
 = Migration of models
 
@@ -14,18 +12,16 @@ There are three different ways to migrate an Aspect Model:
 As soon as the application is started and an Aspect Model with an older version is found in the workspace.
 The migration from a BAMM 2.0.0-based Aspect Model is automatically migrated to the latest SAMM version.
 
+TIP: On this version you can migrate from BAMM 2.0.0 to SAMM 2.0.0.
+In case you have old models based on BAMM 1.0.0 and need to migrate to BAMM 2.0.0 first, please use the Aspect Model Editor in version 4.2.1.
+
 [[loading-old-model]]
 == Loading a (syntactically valid) Aspect Model based on an older version
 
 A migration of an Aspect Model in an old version can also be loaded as usual.
 The tool automatically recognises the older version and migrates it to the latest SAMM version.
 
-image::load-old-model.png[width=100%]
+image::load-old-model.png[]
 
-image::migrate-notification.png[width=200px]
+image:migrate-notification.png[]
 
-++++
-<style>
-  .imageblock {flex-direction: row !important;}
-</style>
-++++

documentation/ame-guide/modules/ROOT/pages/modeling/modeling.adoc

@@ -14,8 +14,8 @@ This section guides you through recurring task with the Aspect Model Editor for
 ***  xref:modeling/trait.adoc[]
 ***  xref:modeling/operation.adoc[]
 ***  xref:modeling/event.adoc[]
+** xref:modeling/connect-elements.adoc[]
 ** xref:modeling/shared-models.adoc[]
 ** xref:modeling/migration-of-models.adoc[]
 ** xref:modeling/model-versions.adoc[Aspect Model versions]
 
-//TODO later rework this chapter to work with the Movement example - we can even show how we changed it for the Semantic Stack commercial version

documentation/ame-guide/modules/ROOT/pages/modeling/shared-models.adoc

@@ -7,25 +7,20 @@ to support you defining model parts, which can be reused in multiple other model
 TIP: In case you want to extract a part of an Aspect Model graph into a "shared model" please make sure to delete the Aspect element from the model. Creating "shared models" proves advantageous, particularly when developing broadly defined elements for use in various Aspect Models.
 
 After deleting the Aspect element, you can choose a new file name to describe the resulting "shared model".
-This file can then be saved in the workspace like any other ttl file. +
+This file can then be saved in the workspace like any other ttl file.
 
-image::shared-model-file-name.png[Save changes in Edit dialog,width=50%]
+image:shared-model-file-name.png[Save changes in Edit dialog,width=50%]
 
 As a result, you create a valid ttl file, which just does not contain the "Aspect" element.
 From all other points of view the lifecycle of such a model is similar with the one of an Aspect Model.
 
-image::shared-model-view.png[width=100%]
+image::shared-model-view.png[]
 
 Such a model can be referenced from multiple other shared models and Aspect Models.
 As soon as you define such a reference the "shared model" it treated like a dependency from the Aspect Model's perspective.
 
 When using the "shared model", the process is the same as with external references, see xref:namespace/use-external-references.adoc[Use external references].
 
-image::use-shared-models.png[width=100%]
+image::use-shared-models.png[]
 
 TIP: In case you need to convert a "shared model" into an Aspect Model, simply add an Aspect element as the first element in the graph.
-++++
-<style>
-  .imageblock {flex-direction: row !important;}
-</style>
-++++

documentation/ame-guide/modules/ROOT/pages/modeling/start-new-models.adoc

@@ -1,24 +1,31 @@
-:page-partial:
-
-[[start-new-models]]
-= Start a new model
+[[new-model]]
+= Create a new model
 
 To start modeling, proceed as follows:
 
-WARNING: Already opened Aspect Models will be lost when loading a new one. Always make sure to save the previous Aspect Model first.
-
-. Click the *New/Load* icon in the xref:getting-started/ui-overview.adoc#toolbar[Toolbar].
-. Click *Create/Upload Aspect Model*.
+. Click the *+* icon in the toolbar.
+. Click *Create/Upload Aspect Model*. +
+image:create-new-model.png[width=80%]
 . Click *Models/Default Aspect Model* to start from the default Aspect Model.
 +
 image::start-modeling-ui.png[width=80%]
 . You can also modify the shown TTL code manually within the text area.
 +
-image::start-modeling-edit-ui.png[width=80%]
+image:start-modeling-edit-ui.png[width=80%]
 . Click *Start modeling*.
 
-++++
-<style>
-  .imageblock {flex-direction: row !important;}
-</style>
-++++
+== Save the model
+
+The model will be saved in your local workspace directory with the name of the Aspect element.
+
+image:save-to-workspace.png[width=80%]
+
+WARNING: If you have already opened an Aspect Model in the Editor and have not saved it before creating or loading a new one, it will be lost.
+Always make sure to save the previous Aspect Model first.
+
+In the Workspace you can find all models stored so far.
+
+image:see-model-in-workspace.png[width=80%]
+
+As you can see in the screenshot, the models are separated by namespace. +
+To learn more about namespaces see xref:namespace/namespaces-references.adoc[].

documentation/ame-guide/modules/ROOT/pages/modeling/trait.adoc

@@ -1,4 +1,4 @@
-= Traits
+= Trait
 [[trait-case]]
 
 There are two ways of adding a Trait:

documentation/ame-guide/modules/ROOT/pages/namespace/export-namespaces.adoc

@@ -4,8 +4,7 @@
 
 To export a namespace, proceed as follows:
 
-. Click *Save* in the xref:getting-started/ui-overview.adoc#toolbar[toolbar].
-+
+. Click *Save* image:toolbar-icons/save.png[] in the toolbar. +
 → A drop-down menu appears.
 . Click *Export Namespace*.
 . Select the available namespace.
@@ -14,14 +13,8 @@ image::select-namespace-export.png[width=100%]
 . Click *Validate*.
 +
 → After validation is done, a summary dialog similar to the one for xref:namespace/import-namespaces.adoc#import-namespaces[namespace import] will be displayed. If the validation has files with errors, the namespace cannot be exported.
-+
-image::export-window.png[width=100%]
-. Click *Export*.
-
+. Click *Export*. +
 → The chosen namespace will be exported.
+. Save the zip file in local file directory.
 
-++++
-<style>
-  .imageblock {flex-direction: row !important;}
-</style>
-++++
+TIP: To export multiple namespaces at once just check multiple boxes at step 3.

documentation/ame-guide/modules/ROOT/pages/namespace/import-namespaces.adoc

@@ -1,5 +1,3 @@
-:page-partial:
-
 [[import-namespaces]]
 = Import namespaces
 
@@ -15,17 +13,23 @@ To import a package with namespaces, proceed as follows:
 → After confirmation, the files inside the ZIP file will be validated.
 +
 image::import-validating.png[width=80%]
-. Click on files in the summary dialog to view the status of it.
+. Click on files in the summary dialog to view the status of it. +
+TIP: In case the zip contains multiple namespaces, the dialog will show them all respectively.
 +
 image::validation-result.png[width=80%]
 . Click *Copy to clipboard* to copy the summary in a JSON-format file for further improvements.
 . Click on one of the options to choose what happens with already existing namespaces.
 +
 * Click *Keep* to keep the existing namespace.
-* Click *Replace* to replace the namespace in the Workspace.
+* Click *Replace* to replace the namespace in the Workspace. +
+NOTE: Be aware that this option will literally overwrite your namespace with this content.
 +
 image::replace-import.png[width=80%]
 . Click *Import* to move your files into the Workspace.
 
-→ Now your namespaces are added to the recent model.
+Now your namespaces are added to the recent model.
+
+
+
+