Outdated Data Transfer Documentation

[mhellmeier]

Bug Report

Describe the Bug

The current data transfer documentation is outdated.

Expected Behavior

Documentation that is in line with the current implementation.

Observed Behavior

Nearly half a year old documentation.

Steps to Reproduce

Steps to reproduce the behavior:

./.

Context Information

https://github.com/eclipse-edc/Connector/tree/main/docs/developer/architecture/data-transfer

Detailed Description

The current status of the data transfer documentation doesn't represent the actual implementation of the Connector.
Two significant issues are:

1. The documentation talks about IDS Info Model and the IDS protocol instead of the new data space protocol (DSP)
2. The connector is always referred to as "Eclipse Dataspace Connector". Besides the change of the name, the current information provided lacks differentiation between the control plane and the data plane, which is essential for developers to build upon it.

[github-actions]

Thanks for your contribution 🔥 We will take a look asap 🚀

[ndr-brt]

thanks for reporting, we already discussed about getting rid of outdated documentation but nobody created the issue yet

[jimmarino]

thanks for reporting, we already discussed about getting rid of outdated documentation but nobody created the issue yet

And PR's would be appreciated!

[mhellmeier]

thanks for reporting, we already discussed about getting rid of outdated documentation but nobody created the issue yet

And PR's would be appreciated!

Maybe it would be a good idea to integrate the documentation update as a mandatory workflow on every pull request. I am talking about a checkbox like this in the pull request template:

• The documentation is up-to-date and represents the current status of the implementation

Otherwise, an issue like this one will continuously be created after some months.

[jimmarino]

thanks for reporting, we already discussed about getting rid of outdated documentation but nobody created the issue yet

And PR's would be appreciated!

Maybe it would be a good idea to integrate the documentation update as a mandatory workflow on every pull request. I am talking about a checkbox like this in the pull request template:

• The documentation is up-to-date and represents the current status of the implementation

Otherwise, an issue like this one will continuously be created after some months.

That is not realistic to ask the committers to do, given their other responsibilities and the fact that many PRs may be required for a single "feature." Documentation is a great way for newcomers to contribute, particularly because it is a good way to get up-to-speed on a project's codebase. Unless people are willing to help out with PRs, I'm afraid the documentation will be less than ideal.

[mhellmeier]

That is not realistic to ask the committers to do, given their other responsibilities and the fact that many PRs may be required for a single "feature."

It is realistic to ask the committers to write the documentation. It is even the duty of the committers to do this.

Committers of the Eclipse foundation have to follow the Eclipse Foundation Project Handbook. This clearly mentions to "[p]provide great documentation" which include "regular updates to your project documentation" (Source: https://www.eclipse.org/projects/handbook/, Community -> Lower the Barriers).

[jimmarino]

That is not realistic to ask the committers to do, given their other responsibilities and the fact that many PRs may be required for a single "feature."

It is realistic to ask the committers to write the documentation. It is even the duty of the committers to do this.

Committers of the Eclipse foundation have to follow the Eclipse Foundation Project Handbook. This clearly mentions to "[p]provide great documentation" which include "regular updates to your project documentation" (Source: https://www.eclipse.org/projects/handbook/, Community -> Lower the Barriers).

Please do not take my statements out of context. I never said committers should not provide updates to the documentation. I said that the proposal to require committers to update end-user documentation on every merged PR and to expect all end-user documentation to be always up-to-date is not realistic.

It's not very productive for you to cite general guidelines we are all aware of and imply that the committers are either ignorant or negligent in their stewardship of the project. If you are displeased with the accuracy or the completeness of the documentation, it would be far more productive if you submitted a PR to improve the situation rather than demand action from the committers.

[paullatzelsperger]

@mhellmeier maybe instead of condescendingly quote regulations at EDC committers, you might feel inclined in contributing something yourself (following our contribution guidelines ofc)? It is after all an open source project...