Merge pull request #1206 from DSD-DBS/fix-documentation

docs: Fix documentation according to user feedback

docs/docs/user/settings/monitoring.md → docs/docs/admin/settings/monitoring.md

@@ -5,9 +5,7 @@
 
 # Pipeline and Model Modifier Monitoring
 
-<!-- prettier-ignore -->
-!!! info
-    Only administrators can see the monitoring dashboard.
-
 To get a general overview of the status of pipelines and model modifiers for
 all registered models, a monitoring dashboard is provided.
+
+You can find it going to `Profile` > `Settings` > `Monitoring`

docs/docs/user/settings/tools/index.md → docs/docs/admin/settings/tools/index.md

@@ -11,10 +11,6 @@ dockerized).
 
 ## Managing Tools
 
-<!-- prettier-ignore -->
-!!! warning
-    To manage tools, you have to be administrator.
-
 The tool management page can be found at `Profile` > `Settings` > `Core` >
 `Tools`. It support the following:
 

docs/docs/user/settings/tools/pure_variants.md → docs/docs/admin/settings/tools/pure_variants.md

@@ -17,7 +17,7 @@
 
 <!-- prettier-ignore -->
 !!! warning
-    The setup can only be performed by administrators. If you want to get access as user, please refer to [Get access to the `pure::variants` license as user](#get-access-to-the-purevariants-license-as-user)
+    The setup can only be performed by administrators. If a user wants to get access, please refer to [Get access to the `pure::variants` license as user](#get-access-to-the-purevariants-license-as-user)
 
 ### Set License Server URL and Upload `license.lic`
 
@@ -50,7 +50,7 @@
 
 1. Open the project perspective of a selected project.
 1. If you don't have model with the `pure::variants` tool yet,
-   [create one](../../projects/models/create.md).
+   [create one](../../../user/projects/models/create.md).
 1. Click on the model restrictions icon: <br />
    ![Model restrictions](./model_restrictions.png){:style="width:400px"}
 1. Enable `Allow the usage of pure::variants`. <br />
@@ -62,5 +62,5 @@
 
 You have to get access to a project with at least one `pure::variants`
 whitelisted model. More information:
-[Get access to a project](../../projects/access.md). If you need a new
+[Get access to a project](../../../user/projects/access.md). If you need a new
 `pure::variants` whitelisted model, please ask your administrator.

docs/docs/user/projects/models/complexity_badge.md

@@ -17,7 +17,7 @@
 
 1.  To set up the model complexity badge, you need to add the Git API URL to
     your Git instance. More information
-    [here](../../settings/model-sources/git.md).
+    [here](../../../admin/settings/model-sources/git.md).
 1.  Link a Git repository to the model, for which you'd like to see the model
     complexity badge.
 

docs/docs/user/projects/models/create.md

@@ -101,6 +101,12 @@ name for the repository and project.
 
 ## Step 4: Metadata
 
-This is an important step. Here, you can select the version and the model
-nature of your tool. If you don't select any version, the functionality will be
-restricted. You will not be able to setup backups or create read-only sessions.
+This is an important step.
+
+Here, you can select the version and the model nature of your tool. If you
+don't select any version, the functionality will be restricted. You will not be
+able to setup backups or create read-only sessions.
+
+If suitable for your project, select one of the latest versions of Capella.
+Older versions may be removed in the future. Make sure your model is up to date
+and in case you update it in time.

docs/docs/user/projects/models/diagrams/setup_diagram_cache.md

@@ -23,9 +23,9 @@
 
     - One pipeline in the linked Git repository should not contain more than 20 jobs.
 
-1. To set up the diagram cache, you need to add the Git API URL to your Gitlab
-   or Github instance. More information
-   [here](../../../settings/model-sources/git.md).
+1. To set up the diagram cache, your administrator needs to add the Git API URL
+   of your Gitlab or Github instance to the collab manager. More information
+   [here](../../../../admin/settings/model-sources/git.md).
 1. Link a Git repository to the model, for which you'd like to see the diagram
    cache.
    <!-- prettier-ignore -->

docs/docs/user/projects/models/metadata.md

@@ -5,6 +5,10 @@
 
 # Update Model Metadata (Version and Nature)
 
+<!-- prettier-ignore -->
+!!! warning
+    Make sure to read the documentation about updating a [TeamForCapella model](../../tools/capella/teamforcapella/update.md) or about updating a [Capella model](../../tools/capella/update.md) first!
+
 1. Navigate to `Projects` and select the project.
 1. In the model overview and select the :material-cog: icon on model you'd like
    to modify.

docs/docs/user/sessions/jupyter/collaboration.md

@@ -28,14 +28,6 @@ connect to your sessions, follow these steps:
 6. **Share the Link**: Distribute the link to all users who should have access.
    They will be able to open your notebooks and concurrently edit them.
 
-#### Instructional Video
-
-Here's a video that visually guides you through these steps:
-
-<video controls>
-  <source src="../jupyter-collaboration.mp4" type="video/mp4">
-</video>
-
 ## Collaboration on Project Level
 
 If you need a shared workspace for notebooks at the project level, you can

docs/docs/user/tools/capella/introduction.md

@@ -31,7 +31,7 @@ Methods for Modeling System of Systems with Capella:
 <iframe width="560" height="315" src="https://www.youtube.com/embed/WCC_iHyChKQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
 If you'd like to learn how Capella works you may want to read through our
-[guide for meta-model exploration](https://dsd-dbs.github.io/py-capellambse/start/how-to-explore-capella-mm.html)
+[guide for meta-model exploration](https://dsd-dbs.github.io/py-capellambse/development/how-to-explore-capella-mm.html)
 
 ## Deriving Model-based Products
 

docs/docs/user/tools/capella/update.md

@@ -0,0 +1,30 @@
+<!--
+ ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->
+
+# Update a Capella Model to a Newer Version
+
+<!-- prettier-ignore -->
+!!! warning
+    Create backups (e.g. in a Git repository) before you start the update process.
+    A downgrade of Capella models is not possible.
+
+<!-- prettier-ignore -->
+!!! info
+    If you want to update a Capella model saved in TeamForCapella, please follow the Capella specific instructions instead:
+    [Update a TeamForCapella based Capella model](../../tools/capella/teamforcapella/update.md)
+
+1. Open a new persistent session with the old Capella version.
+1. Import the model into your workspace.
+1. Terminate the session.
+1. Update the model version to the newer Capella version:
+   [Change model metadata](../../projects/models/metadata.md)
+1. Create a new session with the new Capella version.
+1. In your persistent workspace loaded, execute the following steps:
+   <!-- prettier-ignore -->
+    1. Right click on the model in your workspace.
+    1. Select `Migration` and `Migrate Project toward current version`
+       ![Migrate Capella model](../../tools/capella/teamforcapella/migrate-capella-model.png)
+    1. A backup is  recommended.
+       ![Disable backup option](../../tools/capella/teamforcapella/backup-migration.png)

docs/mkdocs.yml

@@ -22,7 +22,6 @@ nav:
           - Roles: user/projects/roles.md
           - Models:
               - Create a Model: user/projects/models/create.md
-              - Update a Model to a Newer Version: user/projects/models/update.md
               - Update Model Metadata: user/projects/models/metadata.md
               - Model Sources:
                   - TeamForCapella: user/projects/models/sources/t4c.md
@@ -50,19 +49,10 @@ nav:
           - Troubleshooting: user/sessions/troubleshooting.md
           - Jupyter:
               - Collaboration: user/sessions/jupyter/collaboration.md
-      - Settings:
-          - Monitoring: user/settings/monitoring.md
-          - Tools:
-              - General: user/settings/tools/index.md
-              - pure::variants: user/settings/tools/pure_variants.md
-          - Model sources:
-              - Git: user/settings/model-sources/git.md
-              - T4C: user/settings/model-sources/t4c.md
-          - Alerts:
-              - Create an Alert: user/alerts/create.md
       - Tools:
           - Capella:
               - Introduction: user/tools/capella/introduction.md
+              - Update a Capella Model to a Newer Version: user/tools/capella/update.md
               - Co-working Methods: user/tools/capella/t4c-git-compare.md
               - TeamForCapella:
                   - Import a Model from TeamForCapella: user/tools/capella/teamforcapella/import/import-from-t4c.md
@@ -78,6 +68,16 @@ nav:
       - Installation: admin/installation.md
       - Uninstallation: admin/uninstallation.md
       - Getting started: admin/getting_started/getting_started.md
+      - Settings:
+          - Monitoring: admin/settings/monitoring.md
+          - Tools:
+              - General: admin/settings/tools/index.md
+              - pure::variants: admin/settings/tools/pure_variants.md
+          - Model sources:
+              - Git: admin/settings/model-sources/git.md
+              - T4C: admin/settings/model-sources/t4c.md
+          - Alerts:
+              - Create an Alert: admin/alerts/create.md
       - CI templates:
           - Gitlab CI/CD:
               - Image builder: admin/ci-templates/gitlab/image-builder.md