Review Feedback for tutorials section

[stephanbcbauer]

Provided by @SeBuSov Thank you ;) I will create an issue for each section

Feedback

• doc(tutorials): E2E adopter Journey Tutorials review -> End-to-end Adopter Journey #481

  ([https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e])

• Start: Erster Absatz leicht redundant zu folgenden. Aber okay.

• OVERALL: Es fehlt die Nennung/Erläuterung des MXD - später wird
  "auf einmal" vom MXD gesprochen - vielleicht ein zweiter Satz
  direkt am Anfang:

• "This set of tutorials covers the end to end journey of the
  IT department that operates the Catena-X stack for an
  adopter company (data provider / consumer).It includes
  the setup of a minimal set of Catena-X components which is
  called Minimum Tractus-X Dataspace (hereafter MXD)."

• Content: "It also explains the basic connection with the
  services of the core service provider (Confinity-X) for data and
  service
  discovery." https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e#target-audience

  • Wird dies wirklich erklärt? Die Verbindung erfolgt soweit
    ich weiß nicht. Vorschlag:

    • It also explains the basic connection with the core
      services for data and service discovery in a data space,
      as provided by an operating company (e.g. first Catena-X
      Operating Company Confinity-X).

  • Mein Stand war, das Tractus übergreifend verwendet wird:
    Theoretisch kann dies verwirrend sein, wenn Tractus auch für
    Manufacturing-X oder andere Data Spaces genutzt wird und
    dort eine andere OpCo vorliegt -> sehe ich durch Vorschlag
    abgedeckt

• Content/Typo: https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e#goal-of-this-tutorial

  • "This tutorial shall enable the IT department of an adopter
    (data provider/consumer) to operate the minimal Catena-X
    stack that is required to provide or consume data without
    business apps by understanding and implementing

    • The separate technical components

    • Interfaces between components run at the adopter

    • Connection into the wider data space"

    • -> "This tutorial shall enable the IT department of an
      adopter (data provider/consumer) to operate the minimal
      Catena-X stack that is required to provide or consume
      data without business apps by understanding and
      implementing [the]

            1. separate technical components
      
            2. ....\"
      

• Content: "During this tutorial you will get to know the
  perspective of a data provider as well as a data consumer and
  deploy the typical setup that is required for data provisioning
  and data consumption without the help of business
  applications."

  • Repetiv! Absatz vor Aufzählung enthält dies schon. "Minimal
    Catena-X Stack ..."

  • -> "During this tutorial you will get to know the
    perspective of a data provider as well as a data consumer
    and deploy the typical minimal components required."

• Tutorial Description
  (https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e#tutorial-description)

  • Those are linked in the deep
    dive section.
    -> Link funktioniert nicht

• Content: Chapter 3
  Boost https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/#chapter-3-boost -
  "You will then take on the role of a data provider, build your
  first data pipeline, register your data at your decentral
  digital twin registry and create a contract offer in the
  EDC."

  • Not true yet! -> "...data provider, connect a data
    source and create a contract offer in the EDC."

• Typo: "this tutorial is built for employees of the IT
  department who [operates] the IT stack of an adopter
  (data provider/consumer)

  • -> who operate

• Typo "It will not show you [how to further d]evelop
  Catena-X components."

  • -> "It will not show you how
    to [setup] further develop Catena-X
    components."

• Typo/Content "If you fall into one of those three groups,
  please revisit the Catena-X association
  homepage information
  for Application and Service Providers or
  the Community page
  of Tractus-X."

  • genau genommen sind es keine drei gruppen, in die "eine
    Person" fällt

  • -> "If your interest falls into one of those three
    groups, please revisit the Catena-X association
    homepage for information
    for Application and Service Providers or
    the Community page
    of Tractus-X."

 

• doc(tutorials): E2E adopter Journey Tutorials review -> Prerequisites #482  [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/prerequisites/]

• Typo "If you intendend to build your own local
  environment independly from Cloud based offers, you may use
  ths tutorial as well, but you need to ensure, you have
  the rigth technical software stack installed, see below."

  • -> "If you intend to build your own local
    environment independently of Cloud based offers, you may
    use this tutorial as well.In this case you need to
    ensure, you have the right technical software stack
    installed**. Please** see below."

• Typo:

  • "In case you want to install Catena-X components
    or [Kits] directly on your local system you
    need the following:

    • Access to the internet (see next section)

    • One local server instance, either a physical server or a
      virtual machine with at least 2 CPUs 16
      GB [menory] and 20 GB storage

    • Your local system should run a Linux Version (Debian or
      Ubuntu are recommended)

    • You need super user privileges (either root access or
      the right to use sudo)

    • The above tools should be installed (Docker, Kubernetes,
      Kind, Helm, Terraform)"

  • -> Change to: "In case you want to install Catena-X
    components or **[KITs ]**directly on your local
    system you need the following:

    • Access to the internet (see next section)

    • One local server instance, either a physical server or a
      virtual machine with at least 2 CPUs 16
      GB **[RAM ]**and 20 GB storage

    • Your local system should run a Linux Version (Debian or
      Ubuntu are recommended)

    • You need super user privileges (either root access or
      the right to use sudo)

    • The above tools should be installed (Docker, Kubernetes,
      Kind, Helm, Terraform)"

  • HINT: 2CPUs ist oben nicht genannt
    - https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/prerequisites/#required-skills-and-technologies

• Typo:

  • "Most companies run are more complex network, usually
    direct open access to the Internet is not allowed. Firewalls
    and proxy server isolate the local network and most
    communication links are blocked (by blocking ports and
    external URLs)."

    • -> "Most companies run a more complex network**.
      Usually** direct open access to the Internet is not
      allowed. Firewalls and proxy server isolate the local
      network and most communication links are blocked (by
      blocking ports and external URLs)."

• Typo https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/prerequisites/#specific-urls-required-for-mxd

  • Specific URLs​, required for[MxD]

    • M**[X]**D

• Typo

  • apt.releases.hashicorp.com

    • -> "**[.]**apt.releases.hashicorp.com"

• Typo

  • For the [MxD], which is running locally, you
    only need secure shell access, which means port 22 should be
    open.

    • For the [MXD]

• Typo

  • It might be the case, not all of these steps are needed on
    your machine.

    • It might be the case, [that] not all of
      these steps are needed on your machine.

• Typo

  • If not already installed, install a**[ web
    browser]** like firefox
    or **[goggle-]**chrome, you also may need to
    install an x-environment (xterm).

    • -> If not already installed, install a [web
      browser] like firefox or [google
      chrome], you also may need to install an
      x-environment (xterm).

 

• doc(tutorials): E2E adopter Journey Tutorials review -> Chapter 1/ Get an #483

  overview https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/inform/onboardingMaterial

• "More information on the Catena-X initiative can be found at
  the visions and goals section of the association homepage"
  ( https://catena-x.net/en/vision-goals).

  • Link hat sich geändert - würde den hier
    vorschlagen: https://catena-x.net/en/vision
    / https://catena-x.net/en/benefits

• Use Cases "The list of the ten initial use-cases as well as a
  description of each of them can be found
  here:  https://catena-x.net/en/benefits"

  • Link hat sich geändert - use cases jetzt
    hier https://catena-x.net/en/offers

• "The Catena-X Operating Whitepaper describes how the Catena-X
  data space is
  operated":  https://catena-x.net/fileadmin/user_upload/Publikationen_und_WhitePaper_des_Vereins/CX_Operating_Model_Whitepaper_02_12_22.pdf

  • Neues
    Whitepaper https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf

 

• doc(tutorials): E2E adopter Journey Tutorials review -> Chapter 1 Inform / Understand the Architecture #484

  (https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/inform/architecture/#the-different-components)

• Einleitung / erster Satz: "If you are interested more in buying
  services, please get in contact with a operating company."

  • Finde ich etwas unpassend. Würde ich später hinten
    platzieren.

    • -> "This introduction gives you an overview of
      architectural principles of Catena-X. The architecture
      consists of various services, some of which are to be
      operated decentrally for each participant, some to be
      operated centrally or uniquely by an operating company.
      As a reminder: You do not have to setup all the services
      yourself. If you are interested in buying services, you
      can find such on the Marketplace of an operating
      company. Info: ..."

• Sprache: "This section contains more information than is
  currently implemented in the MXD. However, it is intended to
  provide a general overview of the Catena-X
  architecture. However, not all components are listed here."

  • This section contains more information than is currently
    implemented in the MXD**. It** is intended to provide a
    general overview of the Catena-X architecture. However, not
    all components are listed here.

• Unvollständig: "Even if the BPN is already configured and used
  in the MXD setup, its just a dummy. In the real world you will
  receive your BPN via the self description phase within your
  account in the portal**. // ToDo Link to the onboarding
  guide"**

  • Link missing - kenne die file/den Link leider nicht.

  • Für das hier reicht es meiner Ansicht nach auch zu
    schreiben "This Portal is operated by the operating
    company."

• Typo**: "**This is done via policies. Some example policies are
  also part of this tutorial"

  • This is done via policies. Some example policies are also
    part of this tutorial**[.]**

• Typo/Content: "In our setup we already configured two
  EDCs. Àlice and Bob and also the related databases (to
  persist the assets, policies aso.) are ready to use."

  • "In the tutorial we will setup two EDCs, Alice and Bob,
    who form two participants in a data space. Also, we will
    setup the related databases (to persist the assets, policies
    aso.). Also see prerequisites."

• Content: "Registering an EDC is part of the onboarding process
  and is done in the portal. In our setup the EDCs are already
  registered and technical users are already created in the
  KeyCloak instance. Now the minimal Setup for data exchange is in
  place. Now you are able to provide and exchange data."

  • Teil unpassend

  • -> Vorschlag: "Info: In productive usage of Catena-X
    registering an EDC is part of the onboarding process and is
    done in the portal. In our setup the EDCs are already
    registered and technical users are already created in the
    KeyCloak instance." -rest streichen

• CONTENT: "What language does Catena-X speak? / Asset
  Administration Shell with Aspect Models define the language in
  Catena-X" https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/inform/architecture#what-language-does-catena-x-speak--asset-administration-shell-with-aspect-models-define-the-language-in-catena-x

  • Wenn ich es richtig sehe, haben wir noch keine AAS und dDTR
    Inhalte im MXD. Dahingehend wäre mein Vorschlag: Vertiefen
    wir das im nächsten Release des MXD, wenn auch eine dDTR
    etc. dabei ist

  • Vorschlag für Überschrift: "Asset Administration Shell
    and Aspect Models in Catena-X"

  • Vorschlag für Inhalt

    • "In the current MXD Tutorial we will build a data space
      and exchange data according to the protocols of
      Catena-X. However, Catena-X is more than "just" data
      exchange. Catena-X also defines how data is to be made
      available and structured with joint semantics, syntax to
      be interoperable and increase business value. This is
      realized with Asset Administration Shell and
      standardized Aspect Models as a basis for interoperable
      digital twins. Future versions of the MXD will includes
      this. However, currently digital twins are not included.
      You can find further information on the overall
      architecture of Catena-X in the Operating Model
      Whitepaper
      (https://catena-x.net/fileadmin/_online_media_/CX_Operating_Modelv2.1_final.pdf),
      the Catena-X library contents
      (https://catena-x.net/de/library),
      the catena-X Standards library
      (https://catena-x.net/de/standard-library)
      and of course here on Tractus."

• doc(tutorials): E2E adopter Journey Tutorials review -> Feedback: "The different components" #485 : Gut!! Sehr verständlich

  Ggf. direkt die module komplett einfärben: gefüllt grau = not
  covered, Dunkelblau = covered, hellblau = coming
  (https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/inform/architecture/#the-different-components)

• Würde zudem noch einen einleitenden Satz spendieren: "In the
  following picture, the most important elements of Catena-X
  architecture for the MXD are depicted. This architecture will be
  expanded in future versions of the MXD"

 

• doc(tutorials): E2E adopter Journey Tutorials review -> Chapter 3 / Boost Provide #486

  Data https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/boost/provideData/

• LESSONS in "Info-box" (This is the first lesson for this
  tutorial: A contract definition must be created on the data
  provider side. It must always contain an asset, an access policy
  and a contract policy.)
  -https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/boost/provideData/#create-first-contract-definition

• Typo "from a list of slescted partners " -> selected

• Typo "such as the Business Partner Nukber (BPN)." ->
  number

• Typo "Other dta space participants" -> data

• Content - "Other dta space participants than those whose BPN is
  listed in the access policy wouldn't even have the assets in
  their catalog." -> Other data space participants than those
  whose BPN is listed in the access policy wouldn't even be able
  to see the asset in the catalog.

• Content - "Finally Alice can see the Contract Offer from Bob.
  Congratulations on yor first successful data exchange in your
  own data space!" - it is just the first "Meta Data Exchange"
  isn't it? -> "Finally Alice can see the Contract Offer from
  Bob. Congratulations on the first successful offering of data in
  your own data
  space!"  https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/boost/provideData#request-catalog---third-try

• We could end with "continue with "Consuming data" link

• doc(tutorials): E2E adopter Journey Tutorials review -> Chapter 3 / Consume #487

  data https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/boost/consumeData

• Transfer the
  Data https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/boost/consumeData#transfer-the-data

  • Idea: Example Webhook as backend could be used here ->
    "Alice wants to send the data to her backend application
    (" http://backend:8080").
    So she uses the following command to direct the data from
    Asset 3 to her desired data sink. For testing purpose you
    can replace backebd:8080 with your own test-Api or
    use webhook.site as a backend system. Please assure to not
    transfer any sensitive information to webhook."

  • FRAGE: STEHT IRGENDWO, DASS MAN "<XXXX>"
    ersetzen/notieren muss -> e.g. "<contractAgreementID>"
    ist doch eine Ausgabe der vorigen Interaktionen, nicht?

• Typo "Bob has already told Alice that he gave the Asset
  the Id 3, and added a simple description to" -> ID

• Typo "Now she that she is sure which Asset she wants to
  consume, she wants to start the data transfer." -> Now that
  she is

• doc(tutorials): E2E adopter Journey Tutorials review -> Chapter 3 / Restricting users from accessing an asset #488

https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/boost/restrictData

• Create permissive access
  policy https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/blob/feat/tutorials/docs/tutorials/e2e/boost/restrictData#create-a-permissive-access-policy

  • Hier wär am Ende noch ein erläuternder Satz gut nach dem
    curl -> Bob defined a policy which restricts access to
    connector(s) with BusinessPartnerNumber BPNL000000000003. As
    Alice does not own this BPN, she should not be able to
    access the asset.

[stephanbcbauer]

All issues are closed -> discussion can be closed