Merge pull request #1346 from ds-crehm/main

chore(documentation): Update and fix documentation

Author: ds-mwesener

docs/src/docs/administration/backend-configuration.adoc

@@ -11,15 +11,12 @@ The OAuth2, Vault configuration / secrets depend on your setup and might need to
 
 == Helm configuration Trace-X backend (values.yaml)
 
-[source,yaml]
-----
-include::../../../../charts/traceability-foss/values.yaml[lines=121..-1]
-----
+https://github.com/eclipse-tractusx/traceability-foss/blob/main/charts/traceability-foss/values.yaml
 
 === Values explained
 
 ==== <springprofile>
-The different profiles for the different supported environments to bootstrap the resources which are required for the respective environment.
+The profiles for the different supported environments to bootstrap the resources which are required for the respective environment.
 
 |===
 |Springprofile | Description
@@ -43,13 +40,13 @@ BPN (Business Partner Number) for the traceability app used to identify the part
 The jdbc connection string to the database. jdbc:postgresql://${url}:${port}/trace
 
 ==== <datasource.username>
-The username of the datasource e.g. "trace"
+The username of the datasource e.g. "trace".
 
 ==== <datasource.password>
 The password of the datasource or the path to the vault which contains the secret. <path:../data/int/database#tracePassword>
 
 ==== <oauth2.clientId>
-Client ID for OAuth2 (KeyCloak). Request this from your Keycloak operator.
+Client ID for OAuth2 (Keycloak). Request this from your Keycloak operator.
 
 ==== <oauth2.clientSecret>
 Client secret for OAuth2. Request this from your OAuth2 operator.
@@ -64,10 +61,10 @@ The URL of the Keycloak JWK Set. Used by Trace-X to validate tokens when Trace-X
 The client which is used to authenticate the backend.
 
 ==== <edc.apiKey>
-The EDC api key or the path to the secret inside a vault. e.g. <path:../data/int/edc/controlplane#edc.api.control.auth.apikey.value>
+The EDC api key or the path to the secret inside a vault. E.g. <path:../data/int/edc/controlplane#edc.api.control.auth.apikey.value>
 
 === <postgresql.enabled>
-Enables <true> or disables <false> PostgresSQL database.
+Enables <true> or disables <false> the PostgresSQL database.
 
 === <postgresql.auth.postgresPassword>
 Database password for the *postgres* user or the path to the secret inside a vault. <path:.../data/int/database#password>
@@ -76,25 +73,22 @@ Database password for the *postgres* user or the path to the secret inside a vau
 Database password for the application user of the path to the secret inside a vault. <path:.../data/int/database#password>
 
 === <postgresql.auth.database>
-The name  of the database instance.
+The name of the database instance.
 
 === <postgresql.auth.username>
 The user for the database instance.
 
 === <global.enablePrometheus>
-Enables <true> or disables <false> the prometheus instance.
+Enables <true> or disables <false> the Prometheus instance.
 
 === <global.enableGrafana>
-Enables <true> or disables <false> the grafana instance used for resource and application monitoring.
+Enables <true> or disables <false> the Grafana instance used for resource and application monitoring.
 
 === <irs-helm.enabled>
-Enables <true> or disables <false> irs helm charts.
+Enables <true> or disables <false> IRS helm charts.
 
 === <pgadmin4.enabled>
-Enables <true> or disables <false> pgadmin4 console for the PostgreSQL database instance
+Enables <true> or disables <false> pgAdmin 4 console for the PostgreSQL database instance.
 
 === <pgadmin4.ingress.enabled>
-Enables <true> or disables <false> a K8S Ingress for the pgadmin4 console
-
-
-
+Enables <true> or disables <false> a K8S Ingress for the pgAdmin 4 console.

docs/src/docs/administration/configuration.adoc

@@ -5,5 +5,3 @@
 include::frontend-configuration.adoc[leveloffset=+1]
 include::backend-configuration.adoc[leveloffset=+1]
 include::portal-configuration.adoc[leveloffset=+1]
-
-

docs/src/docs/administration/frontend-configuration.adoc

@@ -4,15 +4,14 @@
 :icons: font
 :icon-set: fas
 
-
 Take the following template and adjust the configuration parameters (<placeholders> mark the relevant spots).
 You can define the URLs as well as most of the secrets yourself.
 
 The OAuth2, Vault configuration / secrets depend on your setup and might need to be provided externally.
 
 == Helm configuration Trace-X frontend (values.yaml)
 
-values.yaml https://github.com/eclipse-tractusx/traceability-foss/blob/main/charts/traceability-foss/values.yaml
+https://github.com/eclipse-tractusx/traceability-foss/blob/main/charts/traceability-foss/values.yaml
 
 === Values explained
 
@@ -29,7 +28,7 @@ Annotation for the ingress. E.g. `cert-manager.io/cluster-issuer: letsencrypt-pr
 The hostname of the app.
 
 ==== <ingress.tls>
-The tls settings of the app.
+The TLS settings of the app.
 
 ==== <livenessProbe>
 Following Tractus-X Helm Best Practices https://eclipse-tractusx.github.io/docs/release/

docs/src/docs/administration/installation.adoc

@@ -24,7 +24,7 @@ $ helm install -f your-values.yaml traceability-foss traceability-foss/traceabil
 
 == Dependent values
 
-Following values needs to match in order for application to start and have valid PostgreSQL connection:
+Following values need to match in order for application to start and have a valid PostgreSQL connection:
 
 [source,yaml]
 datasource:

docs/src/docs/administration/portal-configuration.adoc

@@ -6,69 +6,69 @@
 
 The following process is required to successfully connect to the portal:
 
-- Company registration with BPN, Company Name
+- Company registration with BPN and company name
 
-- User Registration with E-Mail
+- User registration with e-mail
 
 - Get e-mail to reset your password
 
 - Reset the password and log in
 
-- Make sure your user has the role App Management
+- Make sure your user has the role 'App Management'
 
-- Navigate to App Overview
+- Navigate to 'App Overview'
 
 - Create app
 
 - Choose a selection of managed roles which is necessary (currently: BPDM, Dataspace Discovery, Semantic Model Management, Identity Wallet Management)
 
-- Wait for app approval by portal
+- Wait for app approval by the portal team
 
 - Subscribe to the app
 
--  As app creator navigate to subscription management - click on configure
+- As app creator navigate to subscription management and click on configure
 
--  Add the frontend url of the application and click approve
+- Add the frontend url of the application and click approve
 
--  Save technical user and secret
+- Save technical user and secret
 
--  Navigate to Register Connector
+- Navigate to 'Register Connector'
 
--  Add managed connector
+- Add managed connector
 
--  Select existing technical user (from app subscription)
+- Select existing technical user (from app subscription)
 
--  Enter name "EDC Provider A"
+- Enter name "EDC Provider A"
 
--  Enter base url of controlplane (EDC)
+- Enter base url of control plane (EDC)
 
--  Confirm
+- Confirm
 
--  Go to other company which want to participate (subscribe)
+- Go to other company which wants to participate (subscribe)
 
--  Login and navigate to app overview
+- Login and navigate to app overview
 
--  Search for the app created
+- Search for the created app
 
--  Subscribe to the app
+- Subscribe to the app
 
--  Go to the app creator company
+- Go to the app creator company
 
--  Navigate to the inbox of the portal
+- Navigate to the inbox of the portal
 
--  Click on the nav link to give approval for the company which want to subscribe
+- Click on the link to give approval for the company which wants to subscribe
 
--  Enter name "EDC Provider B"
+- Enter name "EDC Provider B"
 
--  Enter base url of controlplane (EDC)
+- Enter base url of control plane (EDC)
 
--  Make sure to popuplate the new client id, secrets and app id within trace-x for each company to let it run properly with the new portal configuration.
+- Make sure to populate the new client id, secrets and app id within Trace-X for each company to let it run properly with the new portal configuration.
 
 == Company registration
 https://portal.int.demo.catena-x.net/documentation[How-to]
 
 === Additional info
-Each instance of trace-x reflects an own company, which is associated with one BPN.
+Each instance of Trace-X reflects an own company, which is associated with one BPN.
 
 == User registration
 https://portal.int.demo.catena-x.net/documentation/[How-to]
@@ -80,19 +80,19 @@ The user registration is a self-service. Each user can have one or multiple Trac
 https://portal.int.demo.catena-x.net/documentation/[How-to]
 
 === Additional info
-A connector in the context of trace-x is a Eclipse-Dataspace-Connector. This connector needs to be configured by the public controlplane URL.
+A connector in the context of Trace-X is a Eclipse-Dataspace-Connector. This connector needs to be configured by the public control plane URL.
 
 == App registration
 https://portal.int.demo.catena-x.net/documentation/[How-to]
 
 === Additional info
-A connector in the context of trace-x is a Eclipse-Dataspace-Connector. This connector needs to be configured by the public controlplane URL.
+A connector in the context of trace-x is a Eclipse-Dataspace-Connector. This connector needs to be configured by the public control plane URL.
 
 == Create app subscription
 https://portal.int.demo.catena-x.net/documentation/[How-to]
 
 === Additional info
-An app subscription is necessary to be able to setup a frontend url which will be authorized through keycloak and accessible with the portal.
+An app subscription is necessary to be able to set up a frontend url which will be authorized through Keycloak and accessible with the portal.
 
 == Activate App subscription
 https://portal.int.demo.catena-x.net/documentation/[How-to]

docs/src/docs/administration/system-overview.adoc

@@ -5,11 +5,10 @@ The deployment contains the components required to connect Trace-X to an existin
 * Trace-X frontend
 * Trace-X backend
 
-
 Optionally these components can be installed using the Trace-X backend Helm chart as well:
 
 * PostgreSQL for Trace-X backend
-* pgadmin4
+* pgAdmin 4
 * IRS
 * EDC consumer
 
@@ -28,12 +27,10 @@ Currently, Trace-X API handles three roles: **'User'** and **'Supervisor'** and
 | Category         | Action                         | User       | Supervisor   | Admin
 | View             | View Dashboard                 | x          | x            | x
 |                  | View Parts                     | x          | x            | x
-|                  | View Other parts               | x          | x            | x
 |                  | View Quality notifications     | x          | x            | x
-|                  | View Administration            |            |              | x
-| Edit             | Edit Quality notifications     |            | x            |
-
+|                  | View Administration panel      |            |              | x
 | Quality notification    | Create                         | x          | x            |
+|                         | Edit                           | x          | x            |
 |                         | Send (Approve)                 |            | x            |
 |                         | Read                           | x          | x            | x
 |                         | Cancel                         | x          | x            |
@@ -43,9 +40,6 @@ Currently, Trace-X API handles three roles: **'User'** and **'Supervisor'** and
 |                         | Close                          |            | x            |
 
 | Administration panel  | Access "BPN EDC config panel"    |          |            | x
-|                       | Access "Registry lookup Panel"   |          |            | x
-|                       | Access "Data Import Interface"   |          |            | x
-
+|                       | Access "Registry lookup panel"   |          |            | x
+|                       | Access "Data import interface"   |          |            | x
 |===
-
-

docs/src/docs/administration/troubleshooting.adoc

@@ -1,3 +1,3 @@
 = Troubleshooting
 
-Coming soon...
+Coming soon...

docs/src/docs/arc42/architecture-constraints/index.adoc

@@ -33,14 +33,12 @@
 |Trace-X needs to be Catena-X compliant and the application has to follow the CX standards as well as interact with the core services and components.
 
 |Release as open source
-|The source code - at least partially - is made available as open source and can be found in Github Catena-X ng as well as in Eclipse Tractus-X.
+|The source code - at least partially - is made available as open source and can be found in GitHub Catena-X ng as well as in Eclipse Tractus-X.
 
 |Technology Readiness Level (TRL) for products developed within the CX consortia
 |As Trace-X is a reference implementation, the Technology Readiness Level (TRL) must not be above TRL 8.
 |===
 
-
-
 == Political constraints
 
 |===
@@ -63,5 +61,4 @@
 
 |Test coverage
 |More than 80% of the complete source code has to be test covered.
-
 |===

docs/src/docs/arc42/building-block-view/blackbox-overall.adoc

@@ -13,15 +13,14 @@ include::../../../uml-diagrams/arc42/building-block-view/whitebox_overall.puml[]
 |Components |Description
 
 |IRS
-|The IRS consumes relationship information across the CX-network and builds the graph view. Within this documentation, the focus lies on the IRS.
+|The IRS consumes relationship information across the CX-network and builds the graph view.
 
 |EDC consumer
-|The EDC consumer component is there to fulfill the GAIA-X and IDSA-data sovereignty principles. The EDC consumer consists out of a control plane and a data plane.
+|The EDC consumer component is there to fulfill the GAIA-X and IDSA-data sovereignty principles. The EDC consumer is composed of a control plane and a data plane.
 
 |EDC provider
 |The EDC provider component connects with EDC consumer component and forms the endpoint for the actual exchange of data. It handles automatic contract negotiation and the subsequent exchange of data assets for connected applications.
 
 |Submodel server
 |The submodel server offers endpoints for requesting the submodel aspects.
-
 |===

docs/src/docs/arc42/building-block-view/level-1.adoc

@@ -13,33 +13,32 @@ include::../../../uml-diagrams/arc42/building-block-view/building-block-view.pum
 |Components |Description
 
 |*Trace-X*
-|*Trace-X* is a system allowing the user to review the parts/assets catalogue, start a quality investigations and receive quality alerts.
+|*Trace-X* is a system allowing the user to review the parts / assets catalog and send / receive quality notifications related to those parts.
 
 |*Trace-X API*
-|The *Trace-X API* is the interface over which the data consumer is communicating.
+|The *Trace-X API* is the interface through which the data consumer is communicating.
 
 |*AssetsController*
-|The *AssetsController* provides a REST interface for retrieving the parts/assets information.
+|The *AssetsController* provides a REST interface for retrieving asset information.
 
 |*DashboardController*
-|The *DashboardController* provides a REST interface for retrieving overall statistics displayed on a dashboard screen.
+|The *DashboardController* provides a REST interface for retrieving overall statistics displayed on the dashboard screen.
 
 |*RegistryController*
-|The *RegistryController* provides a REST interface for retrieving the data from parts registry.
+|The *RegistryController* provides a REST interface for retrieving data from the assets registry.
 
 |*ImportController*
 |The *ImportController* provides a REST interface for importing assets and publishing them in the Catena-X network.
 
 |*AssetRepository*
-|The *AssetRepository* is a component responsible for storing and getting assets from database.
+|The *AssetRepository* is a component responsible for storing and getting assets from the database.
 
 |*BPNRepository*
 |The *BPNRepository* is a component which stores BPN -> company name mappings.
 
 |*NotificationsRepository*
-|The *NotificationsRepository* is a component responsible for storing and holding status of sent/received notifications.
+|The *NotificationsRepository* is a component responsible for storing the status and data of sent and received notifications.
 
 |*Database*
-|The *database* is a place for storing assets, relations as well as sent/received notifications.
-
+|The *database* is a place for storing assets, relations and notifications.
 |===