diff --git a/documentation/ame-guide/modules/ROOT/images/ame-ui-overview-numbers.png b/documentation/ame-guide/modules/ROOT/images/ame-ui-overview-numbers.png
index dea0e06e..73f2e6d7 100644
Binary files a/documentation/ame-guide/modules/ROOT/images/ame-ui-overview-numbers.png and b/documentation/ame-guide/modules/ROOT/images/ame-ui-overview-numbers.png differ
diff --git a/documentation/ame-guide/modules/ROOT/images/create-new-model.png b/documentation/ame-guide/modules/ROOT/images/create-new-model.png
new file mode 100644
index 00000000..11b4a91c
Binary files /dev/null and b/documentation/ame-guide/modules/ROOT/images/create-new-model.png differ
diff --git a/documentation/ame-guide/modules/ROOT/images/help-docs.png b/documentation/ame-guide/modules/ROOT/images/help-docs.png
new file mode 100644
index 00000000..a6002279
Binary files /dev/null and b/documentation/ame-guide/modules/ROOT/images/help-docs.png differ
diff --git a/documentation/ame-guide/modules/ROOT/images/migrate-notification.png b/documentation/ame-guide/modules/ROOT/images/migrate-notification.png
index 22db6ff6..0717db4d 100644
Binary files a/documentation/ame-guide/modules/ROOT/images/migrate-notification.png and b/documentation/ame-guide/modules/ROOT/images/migrate-notification.png differ
diff --git a/documentation/ame-guide/modules/ROOT/images/namespace-file-structure.png b/documentation/ame-guide/modules/ROOT/images/namespace-file-structure.png
index a1b43a62..12e44d4f 100644
Binary files a/documentation/ame-guide/modules/ROOT/images/namespace-file-structure.png and b/documentation/ame-guide/modules/ROOT/images/namespace-file-structure.png differ
diff --git a/documentation/ame-guide/modules/ROOT/images/save-to-workspace.png b/documentation/ame-guide/modules/ROOT/images/save-to-workspace.png
new file mode 100644
index 00000000..70672c73
Binary files /dev/null and b/documentation/ame-guide/modules/ROOT/images/save-to-workspace.png differ
diff --git a/documentation/ame-guide/modules/ROOT/images/see-model-in-workspace.png b/documentation/ame-guide/modules/ROOT/images/see-model-in-workspace.png
new file mode 100644
index 00000000..bbfdd048
Binary files /dev/null and b/documentation/ame-guide/modules/ROOT/images/see-model-in-workspace.png differ
diff --git a/documentation/ame-guide/modules/ROOT/images/shared-model-file-name.png b/documentation/ame-guide/modules/ROOT/images/shared-model-file-name.png
index b6bc2aba..52bcf49c 100644
Binary files a/documentation/ame-guide/modules/ROOT/images/shared-model-file-name.png and b/documentation/ame-guide/modules/ROOT/images/shared-model-file-name.png differ
diff --git a/documentation/ame-guide/modules/ROOT/images/workspace-action.png b/documentation/ame-guide/modules/ROOT/images/workspace-action.png
new file mode 100644
index 00000000..c1636ac2
Binary files /dev/null and b/documentation/ame-guide/modules/ROOT/images/workspace-action.png differ
diff --git a/documentation/ame-guide/modules/ROOT/images/workspace-context-menu.png b/documentation/ame-guide/modules/ROOT/images/workspace-context-menu.png
index 7eaa1e9f..e26acca2 100644
Binary files a/documentation/ame-guide/modules/ROOT/images/workspace-context-menu.png and b/documentation/ame-guide/modules/ROOT/images/workspace-context-menu.png differ
diff --git a/documentation/ame-guide/modules/ROOT/images/workspace-warning.png b/documentation/ame-guide/modules/ROOT/images/workspace-warning.png
new file mode 100644
index 00000000..abaf73ac
Binary files /dev/null and b/documentation/ame-guide/modules/ROOT/images/workspace-warning.png differ
diff --git a/documentation/ame-guide/modules/ROOT/nav.adoc b/documentation/ame-guide/modules/ROOT/nav.adoc
index 25863332..a28b9465 100644
--- a/documentation/ame-guide/modules/ROOT/nav.adoc
+++ b/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[]
diff --git a/documentation/ame-guide/modules/ROOT/pages/getting-started/edit-models.adoc b/documentation/ame-guide/modules/ROOT/pages/getting-started/edit-models.adoc
index c7e3b3ea..b08d2c31 100644
--- a/documentation/ame-guide/modules/ROOT/pages/getting-started/edit-models.adoc
+++ b/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
diff --git a/documentation/ame-guide/modules/ROOT/pages/getting-started/ui-overview.adoc b/documentation/ame-guide/modules/ROOT/pages/getting-started/ui-overview.adoc
index a5ee999f..38863e91 100644
--- a/documentation/ame-guide/modules/ROOT/pages/getting-started/ui-overview.adoc
+++ b/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].
-++++
-
-++++
+For more information, see xref:modeling/edit-elements.adoc[Edit elements].
diff --git a/documentation/ame-guide/modules/ROOT/pages/modeling/connect-elements.adoc b/documentation/ame-guide/modules/ROOT/pages/modeling/connect-elements.adoc
new file mode 100644
index 00000000..107a7d2e
--- /dev/null
+++ b/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
diff --git a/documentation/ame-guide/modules/ROOT/pages/modeling/migration-of-models.adoc b/documentation/ame-guide/modules/ROOT/pages/modeling/migration-of-models.adoc
index 1bc0ca19..95680a24 100644
--- a/documentation/ame-guide/modules/ROOT/pages/modeling/migration-of-models.adoc
+++ b/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[]
-++++
-
-++++
diff --git a/documentation/ame-guide/modules/ROOT/pages/modeling/modeling.adoc b/documentation/ame-guide/modules/ROOT/pages/modeling/modeling.adoc
index abdde786..7dadc56f 100644
--- a/documentation/ame-guide/modules/ROOT/pages/modeling/modeling.adoc
+++ b/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
\ No newline at end of file
diff --git a/documentation/ame-guide/modules/ROOT/pages/modeling/shared-models.adoc b/documentation/ame-guide/modules/ROOT/pages/modeling/shared-models.adoc
index 9161106a..a7fba103 100644
--- a/documentation/ame-guide/modules/ROOT/pages/modeling/shared-models.adoc
+++ b/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.
-++++
-
-++++
\ No newline at end of file
diff --git a/documentation/ame-guide/modules/ROOT/pages/modeling/start-new-models.adoc b/documentation/ame-guide/modules/ROOT/pages/modeling/start-new-models.adoc
index 1805f62b..b529088e 100644
--- a/documentation/ame-guide/modules/ROOT/pages/modeling/start-new-models.adoc
+++ b/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*.
-++++
-
-++++
+== 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[].
diff --git a/documentation/ame-guide/modules/ROOT/pages/modeling/trait.adoc b/documentation/ame-guide/modules/ROOT/pages/modeling/trait.adoc
index f69b6736..11de0b07 100644
--- a/documentation/ame-guide/modules/ROOT/pages/modeling/trait.adoc
+++ b/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:
diff --git a/documentation/ame-guide/modules/ROOT/pages/namespace/export-namespaces.adoc b/documentation/ame-guide/modules/ROOT/pages/namespace/export-namespaces.adoc
index ae5e1e88..3ec95b9e 100644
--- a/documentation/ame-guide/modules/ROOT/pages/namespace/export-namespaces.adoc
+++ b/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.
-++++
-
-++++
+TIP: To export multiple namespaces at once just check multiple boxes at step 3.
diff --git a/documentation/ame-guide/modules/ROOT/pages/namespace/import-namespaces.adoc b/documentation/ame-guide/modules/ROOT/pages/namespace/import-namespaces.adoc
index 4f766e3e..51eb1ad2 100644
--- a/documentation/ame-guide/modules/ROOT/pages/namespace/import-namespaces.adoc
+++ b/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.
+
+
+
+
diff --git a/documentation/ame-guide/modules/ROOT/pages/namespace/namespaces-references.adoc b/documentation/ame-guide/modules/ROOT/pages/namespace/namespaces-references.adoc
index 36a3c4e2..c4df92c8 100644
--- a/documentation/ame-guide/modules/ROOT/pages/namespace/namespaces-references.adoc
+++ b/documentation/ame-guide/modules/ROOT/pages/namespace/namespaces-references.adoc
@@ -5,19 +5,7 @@
The Aspect Model Editor supports external references and custom namespaces. The namespaces from which the external elements can be referenced are defined by the folder structure of the Aspect Model Editor file directory.
-[[workspace-directory-folder-structure]]
-== Workspace directory and folder structure on your local machine
-By default, the Aspect Model Editor file directory is located at:
-
-* `+C:\Users\\aspect-model-editor+` (on Windows)
-* `+/Users//aspect-model-editor+` (on Mac or Linux)
-
-There you can add the folder structure for your external references which will then show up in the xref:getting-started/ui-overview.adoc#workspace-sidebar[Workspace sidebar].
-
-image::namespace-file-structure.png[width=100%]
-
-Previous namespaces that do not follow this file structure might not work and might break the external references feature.
[[namespace-view]]
== Namespaces view in the Aspect Model Editor
diff --git a/documentation/ame-guide/modules/ROOT/pages/namespace/workspace.adoc b/documentation/ame-guide/modules/ROOT/pages/namespace/workspace.adoc
new file mode 100644
index 00000000..62eb7304
--- /dev/null
+++ b/documentation/ame-guide/modules/ROOT/pages/namespace/workspace.adoc
@@ -0,0 +1,63 @@
+[[workspace-directory]]
+= Workspace directory
+
+The workspace is a simple folder structure on your local machine.
+
+By default, the Aspect Model Editor file directory is located at following path:
+
+* `+C:\Users\\aspect-model-editor+` (on Windows)
+* `+/Users//aspect-model-editor+` (on Mac or Linux)
+
+There you can add the folder structure for all your Aspect Models.
+On your local file directory you can manually create such folders for the different namespaces and the version.
+Of course creating and deleting namespaces is also possible with this editor**.**
+
+Structure is visible in the xref:getting-started/ui-overview.adoc#workspace-sidebar[Workspace sidebar].
+
+image::namespace-file-structure.png[width=100%]
+
+Namespaces that do not follow this file structure might not work and might break the external references feature.
+
+== Action dialog in workspace
+
+The currently loaded Aspect Model is highlighted gray.
+
+The ... icon next to a model opens the options to
+
+* Delete
+* Load Aspect Model
+* Copy to clipboard
+
+image::workspace-action.png[]
+
+If you just select another Aspect Model, it will not be loaded but its elements will be listed in the left sidebar.
+
+== Create a namespace
+
+TIP: The namespace structure is created automatically if you start with the *+* icon.
+
+* If you select "Create/upload Aspect model", model and later click "Save to Workspace" the folder
+*org.eclipse.digitaltwin* will be created on your file system and the Workspace will show it respectively.
+* If you import a zip with models into your workspace, and it contains valid models with namespaces which
+did not exist in your workplace yet, these will be created additionally.
+
+TIP: In case you have manually added or deleted a file on your local Aspect Model Editor file directory it might happen
+that the change is not instantly visible on the Workspace. In such a case click the *refresh* icon to update the Workspace view.
+
+== Delete a namespace
+
+By deleting the last Aspect Model of a namespace, the folder will be deleted as well.
+
+== Troubleshooting
+=== Aspect Model is marked with a red exclamation mark
+Let us assume you have manually added a new ttl file to the namespace folder on your local file directory
+reserved for the Workspace.
+
+As the file was most probably not created in scope of that namespace, the Aspect Model Editor shows the error marker,
+as it will not be able to load this Aspect Model.
+
+In such a case you will need some expert who can fix it with a text editor.
+
+image::workspace-warning.png[]
+
+=== Aspect Model is marked with a red question mark