Architecture Documentation at eclipse-edc.github.io

[matbmoser]

I am Mathias Moser project lead of the Eclipse Tractus-X project and I am willing to help here and contribute to the Eclipse EDC project and improve the architecture documentation.

My objective is to map the Software Architecture of the system, and also document the overall interactions of the Eclipse Dataspace Connector. To get the "As it is" big picture and until the more technical level mapping is my objective.

I have already started some work in Tractus-X: https://github.com/eclipse-tractusx/sig-architecture/tree/main/docs/patterns/connect%26exchange

But if I am honest, the work that was done here in the EDC project is pretty good and I want to help to document the reality and help on the understanding for developers.

Since I am new to the edc software details, but pretty good in Java, I think that I could help to give an "fresh" perspective on how to bring more quality to the documentation and code documentation.

Lets collaborate to make the EDC more easy to understand and specially now that we have a cool website page, there is place for it ;)

I started also to find out in the current documentation that some pieces are missing and got deprecated: eclipse-edc/eclipse-edc.github.io#74

As mentioned in the discussion:

• There are obvious differences between the DSP & DCP that are extended and implemented in a certain way in the EDC. And this things need to be documented here (is the work I want to do also).

So I will start to bring some proposals to improve the quality.

What you guys think?

[paullatzelsperger]

Helping with documentation and dev easy-of-use is certainly much appreciated.

That said, sentences like "define the overall interactions of EDC" raise several red flags. It is imperative to understand that interactions of EDC are governed by specifications, namely the Dataspace Protocol and the Decentralized Claims Protocol. Any contributions there would have to happen in the respective working groups.

Furthermore, wanting to "define" core elements of a project as a first-time contributor (which is what that sounds like) is not the correct way to approach things, if that is what you meant.

Lastly, please make sure you have thoroughly read, understood and digested all of our existing documentation. It may be a bit scattered, but a lot of it is already there. Discussions, issues and PRs should be focussed and deal with a single, isolated element, such as "repair that broken link here" or "clarify wording in chapter X" as opposed to: "make things more understandable" or "map System Architecture"...

[paullatzelsperger]

There are obvious differences between the DSP & DCP that are extended and implemented in a certain way in the EDC

Keep in mind that DSP and DCP are specifications, that - by their very definition - leave a lot up to the implementation. Which "obvious differences" (as in: "it deviates from the spec") between the specs and the implementations do you see? Those should be addressed.

What would be the correct way in your perspective?

As i mentioned earlier. You start with documentation and minor issues, and you don't go about "defining" stuff (as in: telling us how it has to work).

Maybe I expressed myself with insufficient clarity: we do welcome contributions, so long as they are aligned with the EDC and all its committers.
So again, if you want to contribute documentation, that is a good start and the issue is certainly appreciated!

[matbmoser]

As i mentioned earlier. You start with documentation and minor issues, and you don't go about "defining" stuff (as in: telling us how it has to work).

No one will tell you how to work, I will document the reality "as it is"

[matbmoser]

Maybe I expressed myself with insufficient clarity: we do welcome contributions, so long as they are aligned with the EDC and all its committers.

Sure @paullatzelsperger, and this is exactly what I am doing, asking on the "Forum", then "Creating Discussion", then "Creating Issues" (specific changes), writing in the mailing list. Proposing to do the work myself, What more shall I do?

If I am not following the Eclipse Project Handbook tell me where. Committers are the ones that have the keys sure, but there is also a process to get this alignment done. Meritocracy is everything. Is in our code.

[paullatzelsperger]

all good. maybe i got caught up in the wording. "Defining" things means something different than "describing/documenting" things.

[matbmoser]

all good. maybe i got caught up in the wording. "Defining" things means something different than "describing/documenting" things.

Corrected the wording ;)

[mspiekermann]

I would also like to know what the project lead @mspiekermann thinks about it.

As @paullatzelsperger already wrote, ofc we do welcome contributions! We just need to follow some guidelines as otherwise it becomes a mess. But, you seem to have found the corresponding documents...

Documentation is something we also consider as field of improvement for EDC, so a helping hand is more than welcome + it is a very good starting point for contributions anyway. Feel free to open discussions for larger documentation work proposals or change requests. For smaller additions or corrections just create individual issues and leave your intention to take them over.

I look forward to your contribution!

Just as additional note: We don't use the mailing list to discuss changes on the documentation, it's only used for main announcements. Just keep the work here on Github :)

[jimmarino]

Hi

As @paullatzelsperger and @mspiekermann mentioned, documentation contributions are always welcome and appreciated.

Please note that the documentation you pointed to in Tractus-X does not align with our approach in EDC. Here are a few pointers to help you understand the differences.

How we deal with "architecture" in EDC

We distinguish architecture documents from adopter and contributor documentation.

Architecture documents in this project are placed in the docs/developer directory of a repository. For example, Decision Records. These documents are intended for people working directly with the code base, for example, adding new features or fixing bugs. They are not intended for "adopters" who consume the EDC. Architecture documents are generally written by committers who, by definition, have substantial EDC experience and produce code. They are very rarely written by people not directly involved in the code or non-committers.

One characteristic of our architecture documents is that they are concise, focused on a specific issue, and are not high-level documents typically associated with "enterprise architecture" approaches. That's by design because those types of documents do not provide value in our context. They require too much maintenance, inevitably deviate from the codebase, and are too superficial for the engineers who work on EDC.

Adopter and contributor documentation, by contrast, is intended to help people use and extend EDC. Adopters do need an overview of the system, but they do not need to understand its inner workings. The contributor documentation is focused on explaining how to extend EDC. This requires more low-level detail. The existing documentation is fairly comprehensive and generally does a good job of providing a focused overview of the EDC. However, the EDC documentation is not intended to explain dataspaces, DSP, DCP, or any other standards it implements.

Like EDC developer-focused architecture documentation, "enterprise architecture" documents are not considered useful for adopters or contributors decause they are superficial. Adopters and contributors need precise instructions. We prefer targeted documentation and to rely on samples.

Samples provide the most value

Working code samples are considered the best form of instruction and documentation. That's because:

1. Developers can debug and step through code execution, which is an excellent explanatory tool
2. The samples are less prone to skew and becoming outdated since they can be tested
3. The samples provide templates for developers to start their projects from
4. People are inclined to try code rather than wade through documentation.

Contributing code samples generally yields the most return on investment, so I encourage you to focus on this area.

Adhere to the existing style, structure, and format

The existing documentation structure has served us well, and we have adopted a consistent writing style throughout. Please make sure any contributions follow the existing style (e.g., no marketing, opinions, or hyperbole such as "it's great, it works fast"). Also, please make sure PRs are targeted rather than wide-ranging.

[matbmoser]

Hi

As @paullatzelsperger and @mspiekermann mentioned, documentation contributions are always welcome and appreciated.

Please note that the documentation you pointed to in Tractus-X does not align with our approach in EDC. Here are a few pointers to help you understand the differences.

How we deal with "architecture" in EDC

We distinguish architecture documents from adopter and contributor documentation.

Architecture documents in this project are placed in the docs/developer directory of a repository. For example, Decision Records. These documents are intended for people working directly with the code base, for example, adding new features or fixing bugs. They are not intended for "adopters" who consume the EDC. Architecture documents are generally written by committers who, by definition, have substantial EDC experience and produce code. They are very rarely written by people not directly involved in the code or non-committers.

One characteristic of our architecture documents is that they are concise, focused on a specific issue, and are not high-level documents typically associated with "enterprise architecture" approaches. That's by design because those types of documents do not provide value in our context. They require too much maintenance, inevitably deviate from the codebase, and are too superficial for the engineers who work on EDC.

Adopter and contributor documentation, by contrast, is intended to help people use and extend EDC. Adopters do need an overview of the system, but they do not need to understand its inner workings. The contributor documentation is focused on explaining how to extend EDC. This requires more low-level detail. The existing documentation is fairly comprehensive and generally does a good job of providing a focused overview of the EDC. However, the EDC documentation is not intended to explain dataspaces, DSP, DCP, or any other standards it implements.

Like EDC developer-focused architecture documentation, "enterprise architecture" documents are not considered useful for adopters or contributors decause they are superficial. Adopters and contributors need precise instructions. We prefer targeted documentation and to rely on samples.

Samples provide the most value

Working code samples are considered the best form of instruction and documentation. That's because:

1. Developers can debug and step through code execution, which is an excellent explanatory tool
2. The samples are less prone to skew and becoming outdated since they can be tested
3. The samples provide templates for developers to start their projects from
4. People are inclined to try code rather than wade through documentation.

Contributing code samples generally yields the most return on investment, so I encourage you to focus on this area.

Adhere to the existing style, structure, and format

The existing documentation structure has served us well, and we have adopted a consistent writing style throughout. Please make sure any contributions follow the existing style (e.g., no marketing, opinions, or hyperbole such as "it's great, it works fast"). Also, please make sure PRs are targeted rather than wide-ranging.

Hi @jimmarino Thank you for your feedback.

I saw that there was a task to review the documentation from the repositories and also the current website documentation.
https://github.com/orgs/eclipse-edc/discussions/61#discussioncomment-6656353

I get that the software documentation is mapped in the different products, but for example the existing docs in the Connector are just this:

https://github.com/eclipse-edc/Connector/tree/main/docs/developer/management-domains
And the Decision Records.

I would disagree, sure a "overall architecture" would not help. I get that this repository wants to be kept only at "code" basis, and that is fine for a specific ARC42 approach (which is also not there).
But that makes it really hard to adopt, with just creates an "black box effect". And people do not trust "black boxes", they want to understand how it was built and what is the current status "as it is".

I will follow your guidelines sure that was since the beginning my idea.

Thank you for welcoming me @mspiekermann! I will do as you say!

I would also like to know what the project lead @mspiekermann thinks about it.

As @paullatzelsperger already wrote, ofc we do welcome contributions! We just need to follow some guidelines as otherwise it becomes a mess. But, you seem to have found the corresponding documents...

Documentation is something we also consider as field of improvement for EDC, so a helping hand is more than welcome + it is a very good starting point for contributions anyway. Feel free to open discussions for larger documentation work proposals or change requests. For smaller additions or corrections just create individual issues and leave your intention to take them over.

I look forward to your contribution!

Just as additional note: We don't use the mailing list to discuss changes on the documentation, it's only used for main announcements. Just keep the work here on Github :)

[jimmarino]

I saw that there was a task to review the documentation from the repositories and also the current website documentation. https://github.com/orgs/eclipse-edc/discussions/61#discussioncomment-6656353

That is a two-year-old locked discussion that was created well before the existing documentation.

I get that the software documentation is mapped in the different products, but for example the existing docs in the Connector are just this:

https://github.com/eclipse-edc/Connector/tree/main/docs/developer/management-domains And the Decision Records.

Please look at the main documentation website as well as the individual EDC repositories. There is much more documentation than you refer to above.

I would disagree, sure a "overall architecture" would not help. I get that this repository wants to be kept only at "code" basis, and that is fine for a specific ARC42 approach (which is also not there). But that makes it really hard to adopt, with just creates an "black box effect". And people do not trust "black boxes", they want to understand how it was built and what is the current status "as it is".

I will follow your guidelines sure that was since the beginning my idea.

As I mentioned in my previous comment, many committers view arc42 and other "enterprise architecture" frameworks as superficial. Such frameworks may provide value in other contexts, but EDC is a low-level platform, and we expect our users to be experienced engineers comfortable developing middleware, not end-users who want to deploy a "connector." Consequently, our documentation is tailored to those middleware engineers and in line with other similar open-source projects.