docs: Restructure tools and Capella documentation

- Introduction is updated to also consider other supported tools,
  not just Capella.
- There is a new top-level section "Tools", currently only listing Capella.
- Documentation for "Upload files" has been updated.
- A few typos have been fixed.

docs/user/docs/index.md

@@ -7,64 +7,34 @@
 
 Welcome onboard of the Modeling Collaboration Manager. This platform helps you
 co-work on architectures using tools like
-[Capella](https://www.eclipse.org/capella/) and
-[Papyrus](https://www.eclipse.org/papyrus/).
+[Capella](https://www.eclipse.org/capella/),
+[Papyrus](https://www.eclipse.org/papyrus/),
+[pure::variants](https://www.pure-systems.com/purevariants) and
+[Jupyter](https://jupyter.org/) in combination with
+[py-capellambse](https://github.com/DSD-DBS/py-capellambse).
 
 This platform wraps the modeling tools to create an environment where users can
-work directly in the project context without having to install or configure the
-tool. It also takes care of housekeeping for the modeling projects themselves.
-For example, a automatic backup from
-[TeamForCapella](https://www.obeosoft.com/en/team-for-capella) to any Git
-repository can be set up.
-
-## Ways of co-working on a Modeling Project
-
-In the context of Capella the platform supports 2 main ways of co-working:
-
-<!-- prettier-ignore-start -->
-
-- **Git-only** - the modeling team uses a git repository to work on the model.
-  The team may use git branches to work on features or capabilities in parallel
-  and a main branch is used for integration and release-tagging. This way of
-  working gives the modeling leads / change control board great control over
-  what contents make it to the model that is used for releases (of things like
-  design documentation). On the downside this co-working method is fairly
-  complicated and requires skilled modeling leadership for challenges like
-  merge conflict resolution and fragmentation management (a way to break up
-  model into smaller files to reduce density of merge conflicts).
-- **Git + TeamForCapella** - with this approach the modeling team can co-work
-  with a very high degree of concurrency and stay away from the difficulties of
-  merge conflict resolution. On the downside it is much harder to control what
-  makes it into the model as there is no barrier except for maybe a modeling
-  process that would stop a person from making changes that are not allowed.
-  Yet there are a few ways around that limitation. For teams with basic or no
-  experience in modeling and git this is probably the best way to start
-  co-woking. Git is still used for nightly backup of the model and
-  release-tagging.
-
-    !!! info "Info: TeamForCapella license required"
-        For this co-working method to be enabled you need a valid
-        TeamForCapella license and TeamForCapella server installed and
-        integrated with Collab-Manager.
-
-<!-- prettier-ignore-end -->
+can work directly in the project context without having to install or configure
+the tool. It also takes care of the housekeeping of the modeling projects
+themselves. And that's not all: We also offer project access management and the
+site is completely responsive - and thus also usable on smartphones.
 
 ## Automations and model-derived products
 
-As you can see, git is quite in the middle of the modeling lifecycle. We also
-use its automation means (pre and post-commit handlers, CI/CD) to automate a
-number of housekeeping activities:
+As you can see, Git is quite in the middle of the modeling lifecycle. We also
+use its automation means (CI/CD) to automate a number of housekeeping
+activities:
 
-- Automated model-modifications: this includes range of services like
+- Automated model-modifications: This includes range of services like
   human-friendly element ID assignment, change control and versioning of
-  elements, hyperlinked object title update in descriptions, maintenance of
+  elements, hyperlinked object title update in descriptions and maintenance of
   model-derived requirements (req-bot).
 - Derived product generation and distribution: generation and publication of
   model-derived documents and other artifacts (like software interfaces,
   configurations); caching of diagrams for faster display in linked pages and
   web-viewer; computation of model metrics for modeling progress dashboards;
-  creation of a human-friendly change summary; spell-checking; synchronization
-  with tools like [Simulink](https://mathworks.com/products/simulink.html),
+  spell-checking; synchronization with tools like
+  [Simulink](https://mathworks.com/products/simulink.html),
   [Polarion](https://polarion.plm.automation.siemens.com/),
   [Codebeamer](https://codebeamer.com/),
   [Confluence](https://www.atlassian.com/software/confluence) or even
@@ -78,7 +48,7 @@ to get these configured.
 Now that you have some understanding of the modeling setup and ways of working
 we can look into how you can actually work in this environment.
 
-## Working with Capella in Collaboration Manager
+## Working with Capella in the Collaboration Manager
 
 Capella is not a web native tool, however it runs on Linux - so we can use
 open-source technologies to deliver it to you via browser. We constructed a
@@ -88,11 +58,10 @@ remote connection and [Apache Guacamole](https://guacamole.apache.org/) to
 stream that connection to your browser. We call instances of those containers
 **Sessions**. To make this platform scalable and allow people co-work
 comfortable we use [Kubernetes](https://kubernetes.io/) to run the **Session**
-containers - which in Kubernetes terms are called **Pod**s. Collaboration
-Manager uses Kubernetes to start Sessions. Kubernetes is able to scale the
-cluster to accomodate the active sessions, making it run at reasonable costs in
-both public and private cloud environments (but of course one could run it in a
-VM).
+containers - which in Kubernetes terms are called **Pod**s. Kubernetes is able
+to scale the cluster to accomodate the active sessions, making it run at
+reasonable costs in both public and private cloud environments (but of course
+one could run it in a VM).
 
 There are currently 2 session types supported:
 
@@ -107,6 +76,11 @@ There are currently 2 session types supported:
   enables you to work on projects locally, via git or TeamForCapella as
   persistent workspace keeps "state" even after the session is closed.
 
+We do currently support two different working modes: `TeamForCapella` and
+`Git`. If you want to get more information about it, we have prepared a
+comparison here:
+[Ways of co-working on a Capella project](./tools/capella/t4c-git-compare.md)
+
 ## User Roles
 
 There are 3 roles you can have in a project context:
@@ -124,9 +98,6 @@ There are 3 roles you can have in a project context:
 - **Model manager** - can do same as both users above but also can invite or
   remove users from the managed projects and control their access rights.
 
-You can find more details about
-[how to request a session here](sessions/request.md).
-
 You may also [learn more about the roles model here](projects/roles.md).
 
 ## Next steps

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

@@ -7,7 +7,7 @@
 
 We offer a guided process to create models in a project. To create a model, you
 have to be at least [project lead](../../projects/roles.md). If you're coming
-from project creation, you're ready to go. Otherwise, please naviate to the
+from project creation, you're ready to go. Otherwise, please navigate to the
 _Projects_ tab of the navigation bar, open the project in which you want to
 create a model, and click on the “+” icon.
 

docs/user/docs/sessions/files/files.md

@@ -3,43 +3,51 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-# Upload
+# Browse, upload and download files
 
 <!-- prettier-ignore-start -->
 
-1. Navigate to `Workspaces`
+1. Navigate to the `Session` tab.
 1. On the right side, select the corresponding session. Select the persistent
    session to upload files into your persistent workspace. Click the
-   `Upload button`:
+   `File browser` button:
 
-    ![Upload button](upload-button.png)
+    ![File browser button](file-browser-button.png){:style="width:400px"}
 
-1. Wait until the list of files has loaded.
+1. Wait until the file-tree has loaded.
 
-   ![Upload dialog](upload-dialog.png)
+    ![File browser dialog](upload-dialog.png){:style="width:300px"}
 
-!!! info
-    To upload images into hidden directories, e.g., the workspace
-    metadata, one has to expand these directories by clicking
-    `Show hidden files`
+    !!! info
+         Hidden directories (e.g., the `.metadata` directory) are not
+         visible by default. You can make them visible by clicking on
+         the `Show hidden files` checkbox.
 
-1. Expand the directories until you find the directories where you want to
-   upload your file to. Click the upload button next to the directory name.
+1. You can expand the directories by clicking on the "directory" icon:
 
-   ![Upload files button](upload-file-button.png)
+    ![Expand directory in file browser](expand-directory.png){:style="width:300px"}
 
-1. Now, select the file(s) to upload and confirm. One can see the files to
-   upload marked in green.
+=== "Upload files"
 
-   ![List of files to upload](files-to-upload.png)
+    !!! info
+            It is currently only possible to upload files with a file size of less than 30MB.
+            For larger files we recommend a data transfer via Git.
 
-1. When you're ready and selected all files to upload, then confirm your
-   selection with `Submit`
-1. The upload can take a few seconds/minutes, depending on the file size.
-1. When the upload was successful, the dialog closes without error message.
+      1. Click the `Upload` button on the directory you want to place the file in.
 
-<!-- prettier-ignore-end -->
+          ![Upload files button](upload-files-button.png){:style="width:300px"}
+
+      1. Now, select the file(s) to upload and confirm. The files to be uploaded are marked in green.
+
+         ![List of files to upload](files-to-upload.png)
 
-# Download
+      1. When you're ready and selected all files to upload, confirm your
+         selection with `Submit`.
+      1. The upload can take a few seconds/minutes, depending on the file size.
+      1. When the upload was successful, the dialog closes without error message.
 
-The documentation for the download feature will follow soon.
+=== "Download files"
+
+   Documentation for "Download files" will follow soon.
+
+<!-- prettier-ignore-end -->

docs/user/docs/sessions/types/persistent.md

@@ -7,7 +7,7 @@
 
 <!-- prettier-ignore-start -->
 
-1. To get started with a persistent session, you have to naviate to
+1. To get started with a persistent session, you have to navigate to
    `Sessions`.
 2. Please select the tool and the version you'd like to work with:
     ![Request a persistent workspace](screenshots/request-session.png)
@@ -29,7 +29,7 @@
 
 5. When Capella is loaded you can start working.
 
-    !!! info "Do you need access to a TeamForCapella model"
+    !!! info "Do you need access to a TeamForCapella model?"
         Please continue with the [Connect to a `TeamForCapella` repository guide](../flows/t4c.md).
 
 <!-- prettier-ignore-end -->

docs/user/docs/settings/tools/capella/t4c-git-compare.md → docs/user/docs/tools/capella/t4c-git-compare.md

@@ -84,3 +84,33 @@
     To review changes, the Eclipse EMF diff/merge tool can be used. However, in
     practice this proves to be too time-consuming, as many changes become
     confusing very quickly.
+
+## Some general words
+
+<!-- prettier-ignore-start -->
+
+- **Git-only** - the modeling team uses a git repository to work on the model.
+  The team may use git branches to work on features or capabilities in parallel
+  and a main branch is used for integration and release-tagging. This way of
+  working gives the modeling leads / change control board great control over
+  what contents make it to the model that is used for releases (of things like
+  design documentation). On the downside this co-working method is fairly
+  complicated and requires skilled modeling leadership for challenges like
+  merge conflict resolution and fragmentation management (a way to break up
+  model into smaller files to reduce density of merge conflicts).
+- **Git + TeamForCapella** - with this approach the modeling team can co-work
+  with a very high degree of concurrency and stay away from the difficulties of
+  merge conflict resolution. On the downside it is much harder to control what
+  makes it into the model as there is no barrier except for maybe a modeling
+  process that would stop a person from making changes that are not allowed.
+  Yet there are a few ways around that limitation. For teams with basic or no
+  experience in modeling and git this is probably the best way to start
+  co-woking. Git is still used for nightly backup of the model and
+  release-tagging.
+
+    !!! info "Info: TeamForCapella license required"
+        For this co-working method to be enabled you need a valid
+        TeamForCapella license and TeamForCapella server installed and
+        integrated with Collab-Manager.
+
+<!-- prettier-ignore-end -->

docs/user/docs/tools/capella/teamforcapella/migrate-capella-model.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright DB Netz AG and the capella-collab-manager contributors
+SPDX-License-Identifier: Apache-2.0

docs/user/mkdocs.yml

@@ -6,9 +6,6 @@ theme:
   name: material
 nav:
   - Introduction: index.md
-  - Getting Started:
-      - Overview: getting-started/overview.md
-      - Introduction to Capella: getting-started/capella-intro.md
   - Projects:
       - Get access to a project: projects/access.md
       - Add a user to a project: projects/add-user.md
@@ -41,7 +38,7 @@ nav:
       - Flows:
           - Git: sessions/flows/git.md
           - TeamForCapella: sessions/flows/t4c.md
-      - Files (Upload): sessions/files/files.md
+      - Files browser: sessions/files/files.md
       - Troubleshooting: sessions/troubleshooting.md
       - Jupyter:
           - Collaboration: sessions/jupyter/collaboration.md
@@ -50,19 +47,20 @@ nav:
       - Tools:
           - General: settings/tools/index.md
           - pure::variants: settings/tools/pure_variants.md
-          - Capella:
-              - Co-working methods: settings/tools/capella/t4c-git-compare.md
-              - TeamForCapella:
-                  - Import a model from TeamForCapella: settings/tools/capella/teamforcapella/import/import-from-t4c.md
-                  - Export a model to TeamForCapella: settings/tools/capella/teamforcapella/export/export-to-t4c.md
-                  - TeamForCapella repository management: settings/tools/capella/teamforcapella/repository-management.md
-                  - Update a TeamForCapella based model: settings/tools/capella/teamforcapella/update.md
       - Model sources:
           - Git: settings/model-sources/git.md
       - Alerts:
           - Create an alert: additional/alerts/create.md
           - Delete an alert: additional/alerts/delete.md
-  - User Management: users.md
+  - Tools:
+      - Capella:
+          - Introduction: tools/capella/introduction.md
+          - Co-working methods: tools/capella/t4c-git-compare.md
+          - TeamForCapella:
+              - Import a model from TeamForCapella: tools/capella/teamforcapella/import/import-from-t4c.md
+              - Export a model to TeamForCapella: tools/capella/teamforcapella/export/export-to-t4c.md
+              - TeamForCapella repository management: tools/capella/teamforcapella/repository-management.md
+              - Update a TeamForCapella based model: tools/capella/teamforcapella/update.md
   - Release Notes: release-notes.md
   - About: about.md
 
@@ -82,6 +80,8 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.tabbed:
+      alternate_style: true
 
 extra:
   generator: false