improve docs

docs/docs/queries4tosca/getting-started.md

@@ -1,8 +1,13 @@
 # Getting Started
 
-This section will give a quick introduction to Queries4TOSCA. To run the example queries, you need to have a resolved instance of the
-["Getting Started" template](../getting-started.md){target=_blank}. If you don't have one, follow the steps: 
+There is no standardized way to query TOSCA repositories or instance data. 
+Therefore, we introduce Queries4TOSCA which defined a query language for TOSCA. 
+This language provides a graph-based query language which includes path expressions, filters, and pattern matching. 
+This section will give a quick introduction to Queries4TOSCA.
 
+## Preparation
+
+To run the example queries, you need to install OpenTOSCA Vintner and have a resolved instance of the ["Getting Started" template](../getting-started.md){target=_blank}.
 First, clone the repository. 
 --8<-- "clone.md"
 
@@ -15,7 +20,9 @@ vintner instances create --instance getting-started --template getting-started
 vintner instances resolve --instance getting-started --inputs examples/xopera-getting-started/variability-inputs.example.yaml
 ```
 
-Queries start with a `FROM` statement, followed by either `templates` or `instances` and the template respectively instance name.
+## Example Queries
+
+Queries start with a `FROM` statement, followed by either `templates` or `instances` and the name of the template or the name of the instance, respectively.
 Inside a `SELECT` statement, you can enter a path to the data that you want to return.
 
 To get the entire contents of the template, run the following command.
@@ -107,7 +114,7 @@ You can use an asterisk as a wildcard operator to get all child elements. The fo
 
 
 You can also specify a predicate in square brackets after any part of the path expression to filter elements.
-The following command will return only nodes of type `textfile`, which may be `first` or `second`, depending on how you resolved the template.
+The following command will return only nodes of type `textfile`.
 
 === "Query"
     ```shell linenums="1"
@@ -159,8 +166,8 @@ Note the lack of quotation marks - we are using a value from the template for bo
     - first: textfile
     ```
 
-`MATCH` statements are used to match patterns in the topology of a template. You can "draw" the pattern by surrounding nodes 
-with parentheses and connect them to other nodes via arrows. The following statement will return all nodes that have a requirement fulfilled by `localhost`.
+`MATCH` statements are used to match patterns in the topology of a template. You can "draw" the pattern by surrounding nodes with parentheses and connect them to other nodes via arrows.
+The following statement will return all nodes that have a requirement fulfilled by `localhost`.
 
 === "Query"
     ```shell linenums="1"
@@ -180,3 +187,6 @@ with parentheses and connect them to other nodes via arrows. The following state
         - host:
             node: localhost
     ```
+
+This is just a simple example.
+In a more complex scenario, it would be possible, e.g., to dynamically access the public address of a virtual machine which hosts a database to which a specific component connects.

docs/docs/queries4tosca/specification.md

@@ -80,7 +80,7 @@ Here are some examples.
 
 ```text linenums="1"
 node_templates.localhost       // Selecting a node directly by name
-node_templates.localhost.#     // Selecting attributes a node
+node_templates.localhost.#     // Selecting attributes of a node
 node_templates.*               // Selecting all nodes
 GROUP(my-group)                // Selecting all nodes in group 'my-group'
 POLICY(my-policy)              // Selecting all nodes targeted by policy 'my-policy'
@@ -133,7 +133,7 @@ evaluates to true.
 
 ```text linenums="1"
 node_templates.*[type='textfile' AND name='first']
-node_templates.*[name='frist' OR name='second']
+node_templates.*[name='first' OR name='second']
 ```
 
 ### Return Structures
@@ -201,7 +201,7 @@ in the middle of the arrow.
 
 It is also possible to search for node templates connected over multiple relationships by specifying a
 cardinality. This can be accomplished by putting an asterisk at the end of a relationship, followed
-optionally by a number or a range. If both are omitted, relationships of any length will be matched.
+optionally by a number or a range.
 
 ```text linenums="1"
 (a)-{*2}->(b)       // exactly two hops between a and b
@@ -211,7 +211,9 @@ optionally by a number or a range. If both are omitted, relationships of any len
 (a)-{*}->(b)        // any amount of hops
 ```
 
-## Grammar 
+## Appendix A "Grammar" 
+
+This appendix contains the complete [Ohm](https://ohmjs.org){target=_blank} grammar of Queries4TOSCA.
 
 ```text linenums="1"
 Query {

docs/docs/sofdcar/profile.md

@@ -9,7 +9,7 @@ title: Profile
 This document specifies the TOSCA Software-Defined Car (SofDCar) profile.
 This profile includes normative TOSCA types for the domain of software-defined cars. 
 Standardizing such normative TOSCA types improves interoperability.
-For example, an ECU supplier can model and distribute the deployment and management of his ECUs using these types. 
+For example, an ECU supplier can model and distribute the deployment and management of their ECUs using these types. 
 Various OEMs can then import provided models and integrate them into their cars.
 The specification is under active development and is not backwards compatible with any previous versions.
 

docs/docs/sofdcar/tosca-sofdcar-profile-non-normative.md

@@ -5,7 +5,7 @@ We specify the following node types.
 
 #### sofdcar.nodes.Python.Application
 
-Non-normative python application running on an HPC. This application required a python runtime.
+Non-normative python application running on an HPC. This application requires a python runtime.
 
 
 ```yaml linenums="1"
@@ -36,13 +36,13 @@ sofdcar.nodes.Python.Runtime:
         relationship: tosca.relationships.HostedOn
 ```
 
-#### sofdcar.nodes.RaspberryPi
+#### sofdcar.nodes.RaspberryPi.Hardware
 
-The hardware of an Raspberry Pi serving as a HPC hardware. This Raspberry Pi is able to host HPC software.  Furthermore, the Raspberry Pi is able to directly host python applications without explicit python runtime since a python runtime is already installed on the Raspberry Pi.
+The hardware of an Raspberry Pi serving as a HPC hardware. This Raspberry Pi is able to host HPC software. Furthermore, the Raspberry Pi is able to directly host python applications without explicit python runtime since a python runtime is already installed on the Raspberry Pi.
 
 
 ```yaml linenums="1"
-sofdcar.nodes.RaspberryPi:
+sofdcar.nodes.RaspberryPi.Hardware:
   derived_from: sofdcar.nodes.HPC.Hardware
   capabilities:
     host:

docs/docs/sofdcar/tosca-sofdcar-profile-non-normative.yaml

@@ -23,7 +23,7 @@ node_types:
     sofdcar.nodes.Python.Application:
         description: >
             Non-normative python application running on an HPC.
-            This application required a python runtime.
+            This application requires a python runtime.
         derived_from: sofdcar.nodes.HPC.Software
         requirements:
             - host:

docs/docs/sofdcar/tosca-sofdcar-profile.md

@@ -54,7 +54,7 @@ sofdcar.capabilities.Host.ECU.Software:
 
 #### sofdcar.capabilities.OperatingSystem.RealTime
 
-The capability to provide an OS with real time
+The capability to provide a real-time operating system.
 
 ```yaml linenums="1"
 sofdcar.capabilities.OperatingSystem.RealTime:
@@ -382,7 +382,7 @@ The node all other accelerators are derived from.
 
 ```yaml linenums="1"
 sofdcar.nodes.Accelerator:
-  derived_from: sofdcar.nodes.Root
+  derived_from: sofdcar.nodes.Actuator
 ```
 
 #### sofdcar.nodes.Brake
@@ -391,7 +391,7 @@ The node all other brakes are derived from.
 
 ```yaml linenums="1"
 sofdcar.nodes.Brake:
-  derived_from: sofdcar.nodes.Root
+  derived_from: sofdcar.nodes.Actuator
 ```
 
 #### sofdcar.nodes.Steering
@@ -400,7 +400,7 @@ The node all other steerings are derived from.
 
 ```yaml linenums="1"
 sofdcar.nodes.Steering:
-  derived_from: sofdcar.nodes.Root
+  derived_from: sofdcar.nodes.Actuator
 ```
 
 #### sofdcar.nodes.Sensor

docs/docs/sofdcar/tosca-sofdcar-profile.yaml

@@ -64,7 +64,7 @@ capability_types:
         derived_from: tosca.capabilities.Container
 
     sofdcar.capabilities.OperatingSystem.RealTime:
-        description: The capability to provide an OS with real time
+        description: The capability to provide a real-time operating system.
         derived_from: tosca.capabilities.OperatingSystem
         properties:
             time_guarantee:
@@ -254,15 +254,15 @@ node_types:
 
     sofdcar.nodes.Accelerator:
         description: The node all other accelerators are derived from.
-        derived_from: sofdcar.nodes.Root
+        derived_from: sofdcar.nodes.Actuator
 
     sofdcar.nodes.Brake:
         description: The node all other brakes are derived from.
-        derived_from: sofdcar.nodes.Root
+        derived_from: sofdcar.nodes.Actuator
 
     sofdcar.nodes.Steering:
         description: The node all other steerings are derived from.
-        derived_from: sofdcar.nodes.Root
+        derived_from: sofdcar.nodes.Actuator
 
     sofdcar.nodes.Sensor:
         description: The node all other sensors are derived from.

docs/docs/variability4tosca/guides/artifacts/index.md

@@ -28,19 +28,15 @@ curl -fsSL https://vintner.opentosca.org/install.sh | sudo bash -
 vintner setup init
 ```
 
-## Orchestrator
-
-We currently support xOpera and Unfurl.
-Since both can only be installed on Linux, we implemented a WSL integration for both.
-In our case, we run on a Linux machine and use Unfurl.
+Next, we configure Unfurl as the orchestrator that should be used for the deployment.
 For more information see [Orchestrators](../../../orchestrators.md){target=_blank}.
 
 ```shell linenums="1"
 vintner orchestrators init unfurl
 vintner orchestrators enable --orchestrator unfurl
 ```
 
-## Import 
+## Import the Template
 
 !!! Warning "TODO"
     - figures for vst
@@ -107,7 +103,8 @@ Afterward, you can undeploy the application.
 vintner instances undeploy --instance artifacts
 ```
 
-You can also optionally remove the instance and cleanup your filesystem (this will also removes other instances from the filesystem).
+You can also optionally remove the instance or cleanup your filesystem.
+Note, cleaning up the filesystem removes any vintner data including, e.g., all imported templates and created instances.
 
 ```shell linenums="1"
 # (optional) Delete instance

docs/docs/variability4tosca/guides/pipes-and-filters/index.md

@@ -30,11 +30,7 @@ curl -fsSL https://vintner.opentosca.org/install.sh | sudo bash -
 vintner setup init
 ```
 
-## Orchestrator
-
-We currently support xOpera and Unfurl.
-Since both can only be installed on Linux, we implemented a WSL integration for both.
-In our case, we run on a Linux machine and use xOpera.
+Next, we need to configure xOpera as the orchestrator that should be used for the deployment.
 For more information see [Orchestrators](../../../orchestrators.md){target=_blank}.
 
 ```shell linenums="1"

docs/docs/variability4tosca/guides/pruning/index.md

@@ -20,11 +20,7 @@ curl -fsSL https://vintner.opentosca.org/install.sh | sudo bash -
 vintner setup init
 ```
 
-## Orchestrator
-
-We currently support xOpera and Unfurl.
-Since both can only be installed on Linux, we implemented a WSL integration for both.
-In our case, we run on a Linux machine and use xOpera.
+Next, we need to configure xOpera as the orchestrator that should be used for the deployment.
 For more information see [Orchestrators](../../../orchestrators.md){target=_blank}.
 
 ```shell linenums="1"

docs/docs/variability4tosca/motivation/index.md

@@ -1,18 +1,19 @@
 # Motivation
 
-In the following, we provide a detailed step-by-step tutorial to deploy the development variant of the motivating scenario.
-The motivating scenario is a simple composite application that consists a web component and database.
+In the following, we provide a detailed step-by-step tutorial to deploy the development variant of the motivating scenario, as presented in Figure 1.
+The motivating scenario is a simple composite application that consists of a web component and a database.
 This application can be deployed in different variants.
-During development the application should be deployed on a single virtual machine whereas during production an elastic deployment is required and, therefore, the application is deployed on GCP.
+During development the application should be deployed on a single virtual machine.
+However, for the productive operation, an elastic deployment is required and, therefore, the application is deployed on Google Cloud Platform (GCP).
 
 <figure markdown>
   ![Motivating Scenario](motivation.png){width="700"}
-  <figcaption>Figure 1: Motivating Scenario</figcaption>
+  <figcaption>Figure 1: The TOSCA models of our motivating scenario. The development variant on the left and the production variant on the right.</figcaption>
 </figure>
 
 ## Requirements
 
-You to fulfill the following requirements to follow this walkthrough.
+You need to fulfill the following requirements to follow this step-by-step tutorial.
 
 - Access to an OpenStack instance
 - A machine having Ubuntu22.04 LTS installed
@@ -31,21 +32,19 @@ curl -fsSL https://vintner.opentosca.org/install.sh | sudo bash -
 vintner setup init
 ```
 
-We currently support xOpera and Unfurl.
-Since both can only be installed on Linux, we implemented a WSL integration for both.
-In our case, we run on a Linux machine and use xOpera.
+Next, we need to configure xOpera as the orchestrator that should be used for the deployment.
 For more information see [Orchestrators](../../orchestrators.md){target=_blank}.
 
 ```shell linenums="1"
 vintner orchestrators init xopera
 vintner orchestrators enable --orchestrator xopera
 ```
 
-## Import
+## Import the Template
 
 <figure markdown>
   ![Motivating Scenario](variable-service-template.png){width="700"}
-  <figcaption>Figure 2: Variable Service Template</figcaption>
+  <figcaption>Figure 2: The Variability4TOSCA service template (variable service template) of our motivating scenario.</figcaption>
 </figure>
 
 First, we clone the repository.
@@ -63,7 +62,7 @@ vintner instances create --instance motivation --template motivation
 ```
 
 We can optionally inspect the variable service template.
-This template contains all possible elements having conditions assigned.
+This template contains all possible elements having conditions assigned, as presented in Figure 2.
 For example, the virtual machine hosted on OpenStack has a condition assigned that checks if the development variant has been chosen.
 
 ```shell linenums="1"
@@ -76,15 +75,15 @@ vintner templates inspect --template motivation
 
 We intend to deploy the development variant of the application.
 Therefore, we need to resolve the variability by providing respective variability inputs.
-In our case, we can use an already predefined variability preset.
+In our case, we can use already predefined variability inputs by using a variability preset.
 
 ```shell linenums="1"
 # Resolve variability
 vintner instances resolve --instance motivation --presets dev
 ```
 
 You can optionally inspect the generated service template. 
-This template contains only the nodes required for the development variant.
+This template contains only the nodes required for the development variant, as presented on the left in Figure 1.
 
 ```shell linenums="1"
 # (optional) Inspect service template
@@ -114,7 +113,8 @@ Afterward, you can undeploy the application.
 vintner instances undeploy --instance motivation
 ```
 
-You can also optionally remove the instance and cleanup your filesystem (this will also removes other instances from the filesystem).
+You can also optionally remove the instance or cleanup your filesystem.
+Note, cleaning up the filesystem removes any vintner data including, e.g., all imported templates and created instances.
 
 ```shell linenums="1"
 # (optional) Delete instance