Future "Connector Kit" documentation

[stephanbcbauer]

Current situation

The current documentation of the Connector Kit is more or less a documentation of the tractusx-edc => The whole repository (filtered for MD files) is taken and copied to GitHub.io:

• folder structure tractusx-edc
• folder structure GitHub.io

The reason here was the initial idea to document the tractus-x edc in GitHub.io. In a different structure. MD files are structured differently:

• Adoption View
• Development View
• Operation View

But documenting the whole reference implementation is not the purpose of Kits. => See future working model.

First files were copied (sporadically, or before releases) from tractusx-edc to GitHub.io repository. This is/was a lot of manual effort => an automatic process was developed, but this process is only needed if we really need 90 % (this number is not fix) from tractusx-edc documentation. If we decide to divide the two types of documentation, it's probably not needed any more.

Future working model

Expected Artifacts in a KIT (Operating Model)

It is not needed to document the full reference implementation (the tractusx-edc is the reference implementation). So, for example, instead of documenting all the extensions (within the kit), we could document a more general way. Of course, the detailed documentation should stay in the tractusx-edc repository. Cause it belongs to the code and the reference implementation.

Suggestion for a new and clean start (if we want to handle these two ways as entirely different documentation types)

1. delete KIT document in tractusx-edc, this means this folder is not needed any more. It's currently also located on GitHub.io
2. rename this folder to Connect Kit
3. Start step by step deleting files in this folder which are to much or not needed to full fill the requirements of a Kit.

[stephanbcbauer]

@arnoweiss @stefan-ettl @danielmiehle @maximilianong @bcronin90

[arnoweiss]

I like the approach. Additional thoughts:

• Developer Documentation does not belong in the Kit but in the implementations' repos.
• Focus on stakeholder problems: How to deploy and how to use?
• Avoid redundancies. Currently, there's like three different sections on POSTing Assets against the management API and all have contradicting examples.

[stephanbcbauer]

thx for this feedback @arnoweiss . Totally agree.

[arnoweiss]

How do we proceed?

[maximilianong]

What do we want to achieve with the KIT? We want make it as easy as possible for our stakeholders to work with that stuff and everything at one place - not moving to different repositories, different pages ..

E.g.:
You are App-Provider ABC, you want to bring your solution to the marketplace of Catena-X and be compliant with our data sovereignty guardrails - so you need a documentation on what the app needs to do.

If this is covered with the new structure - I'm happy 🕺

[stephanbcbauer]

@maximilianong At least right now it's not covered, or it's too complicated.

[bcronin90]

The current documentation of the Connector Kit is more or less a documentation of the tractusx-edc => The whole repository (filtered for MD files) is taken and copied to GitHub.io:
That is no longer the case on tx-edc side. Only select files are added to the documentation release. That mechanism is imo fine, though if we want to change the files selected or their contents, I am of course willing to help.

First files were copied (sporadically, or before releases) from tractusx-edc to GitHub.io repository. This is/was a lot of manual effort => an eclipse-tractusx/tractusx-edc#715 was developed, but this process is only needed if we really need 90 % (this number is not fix) from tractusx-edc documentation. If we decide to divide the two types of documentation, it's probably not needed any more.
If we want to keep the tx-edc repository as the single source for tx-edc documentation, then the process is still needed. Otherwise it isn't.

1. delete KIT document in tractusx-edc, this means this folder is not needed any more. It's currently also located on GitHub.io
   That is the barebone documentation that is currently expanded upon automatically to create the connector kit documentation. As it stands right now, they are both needed, as the one in tx-edc is used to create the one in gh.io
2. rename this folder to Connect Kit
   That is actually part of my open PR.

This process as detailed only makes sense if we want to maintain a second, separate documentation for tx-edc outside of the tx-edc repository. We should be very certain we want that before doing anything drastic. There are a few concerns to keep in mind:

1. Who is going to maintain this separate documentation? Which organization and which people?
2. How do we ensure it's up-to-date?
3. What do we want this new documentation to actually say? And how much can we even use of the old documentation?

Before these are addressed, I would advise against proceeding.

[stephanbcbauer]

@bcronin90 thx for your feedback. So to be honest, we documented not as expected. So yes, it is a second documentation because the focus is different. Until now, we documented the tractusx-edc with the Connector Kit, but it should be more “general”, a specification, a “standard”. The tractusx-edc documentation is a documentation for one reference implementation.

to answer your question:

1. The community via the release process (thats the goal) -> there are already Qgate tickets for the KITs. And right now documentation is already planned by @stefan-ettl in every PI/Release
2. not sure what to answer, same way we did before?
3. I think @maximilianong already answered the question and i think we can definitly reuse some parts... for example the new adoption view... there is no need to change

[arnoweiss]

I think the repo should include dev-docs, notes on deployment etc and the Kit should specify HOW a piece of software (or ideally protocol) should be used.

[bcronin90]

Alright. Then we should probably take some time to define which questions the new documentation should answer and how we are going to structure that.

[stephanbcbauer]

Agree with both comments. Thank you, @arnoweiss , @bcronin90