docs(terminology): extended and updated terminology #1653

janpmeyer · 2022-07-12T12:50:56Z

What this PR changes/adds

The documentation on terminology has been extended and adapted.

Why it does that

The previous documentation under the area of terminology has not been complete so far and has been partly outdated.

Linked Issue(s)

Closes #1306

Checklist

added appropriate tests?
performed checkstyle check locally?
added/updated copyright headers?
documented public classes/methods?
added/updated relevant documentation?
added relevant details to the changelog? (skip with label no-changelog)
formatted title correctly?

…erminology

…anager

paullatzelsperger

Explanations, that deal with actual Java classes, should be put into the respective Javadoc comments. Also, many of the explanations are completely redundant. Please do not just paraphrase the class name, because that does not add value.

Documenting something in a markdown file should only be done if it cannot be done in Javadoc, e.g. overarching or architectural concepts.

The terminology.md really is useful to explain more abstract or overarching concepts such as "Dataspace" or "Extension", as long as they are correct.

paullatzelsperger · 2022-07-12T14:08:12Z

docs/overview/terminology.md

+| **Contract Offer Template**  | Blueprint of a **contract offer**
+| **Consumer**                 | see **data consumer**
+| **Consumer Pull**            | The data transfer is initilazied by the Consumer
+| **Data**                     | **Data** describes the properties of business objects


That is plain wrong. Business objects' properties are described by fields, at least in an OOP sense.

I have tried to reformulate it in the sense that data have the task to represent information. Honestly, however, a good description for data is to be found, because from different points of view data are always defined slightly differently. Hope it fits better now.

paullatzelsperger · 2022-07-12T14:08:30Z

docs/overview/terminology.md

+| **Contract Agreement**       | **Contract Agreement**<p>* points to a **Contract Offer**<p>* results from a **Contract Negotiation Process**<p>* has a start date and may have a expiry date and a cancellation date
+| **Contract Negotiation**     | * MVP: only possible to accept already offered contracts. Counter offers are rejected automatically.
+| **Contract Offer**           | **Contract offer**<p>* set of obligations and permissions<p>* generated on the fly on provider side (see **Contract Offer Framework**)<p>* are immutable<p>* persisted in **contract negotiation process** once the negotiation has started<p>
+| **Contract Offer Framework** | **Contract offer framework**<p>* generates **contract offer templates**<p>* provided by **extensions**<p>* may be implemented in custom **extensions** to created **contract offers** based on existing systems


The term "Contract Offer Framework" is not in use anymore.

Ok sorry, deleted it now. I wasn't aware of it.

paullatzelsperger · 2022-07-12T14:09:36Z

docs/overview/terminology.md

+| **Federated Catalog**        | A decentralized **catalog**
+| **Framework**                | see **contract offer framework**
+| **Health**                   | Infrastructure status of the EDC
+| **HTTPDataAddress**          | Specific type of **dataaddress** in context of HTTP-endpoints


HTTPDataDdress: yeah, but which one?

Deleted this term now in context of your advice that something like this should be in the javadoc and not in an markdown.

paullatzelsperger · 2022-07-12T14:09:46Z

docs/overview/terminology.md

+| **Event Router**             | **Event router** is the central part of the **event framework**, which collects all published **events**
+| **Extension**                | see **EDC Extension**
+| **Federated Catalog**        | A decentralized **catalog**
+| **Framework**                | see **contract offer framework**


see comment there.

paullatzelsperger · 2022-07-12T14:10:20Z

docs/overview/terminology.md

+| **Event Framework**          | **The event framework** is a way to react to actions in the EDC and can also be extended
+| **Event Router**             | **Event router** is the central part of the **event framework**, which collects all published **events**
+| **Extension**                | see **EDC Extension**
+| **Federated Catalog**        | A decentralized **catalog**


since Catalog and Federated Catalog are two entries here, it would be necessary to distinguish between them.

I have now tried to better illustrate that the catalog is a standalone component of a dataspace, while the federated catalog is a decentralized approach that is placed within each connector.

paullatzelsperger · 2022-07-12T14:10:37Z

docs/overview/terminology.md

+| **Health**                   | Infrastructure status of the EDC
+| **HTTPDataAddress**          | Specific type of **dataaddress** in context of HTTP-endpoints
+| **Identity Provider**        | Management of the correct identification of all participants in the **dataspace**.
+| **Injection**                | **Artifacts**/**EDC Extensions** can be injected in different parts of the EDC to be used 


Injection: That's just plain wrong.

I deleted this also because of your advice in context of what has to be in javadoc and what in markdown.

Only my question about it is this. The Injection Interface is used to make the different modules usable among each other. So to give a module of the EDC the possibility to find the COde of another used module within the EDC. If this is a complete misconception of your injection mechanism, I need to look deeper into your injection mechanism.

first of all, we don't inject extensions or modules, we simply inject services. this is a very wide-spread concept that deals with object instantiation.
Here, we use it to achieve loose coupling through interfaces, and determine the runtime type of a field ... well... at runtime.

I strongly suggest diving deeper into the code and reading the appropriate documentation, and only add documentation if really necessary.

…request

jimmarino · 2022-07-13T07:33:28Z

Part of my issue with the documentation in general (not related just to this PR) is that it is mixing concepts with implementation details and duplicating this in multiple places. @janpmeyer unfortunately this problem pre-dates your work here but I think we should address it now before it gets worse.

For example, we have conceptual documentation here:

https://github.com/eclipse-dataspaceconnector/Publications/blob/main/Dataspaces/Dataspace%20Context%20Model%20and%20Conceptual%20Architecture.md

and here:

https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/tree/main/docs/architecture/diagrams

Parts of the terminology in this PR are not aligned with either. For example, in EDC there is no concept of a broker in the IDS sense, just FCNs and FCCs. A connector is not responsible for handling the process of joining a dataspace, etc.

Can we first align on an overall strategy for the documentation? As a starter, I agree with @paullatzelsperger that implementation details - items which are not represented at a conceptual level - should only be described in Javadoc and referenced in technical implementation documentation (e.g. a Decision Record). For example, AssetIndex is an implementation detail, not a concept like a Connector or a Participant Agent.

If we adopt that approach, shouldn't terminology be defined as part of the conceptual architecture document?

github-actions · 2022-07-21T03:22:15Z

This pull request is stale because it has been open for 7 days with no activity.

github-actions · 2022-07-29T03:33:02Z

This pull request was closed because it has been inactive for 7 days since being marked as stale.

janpmeyer added 5 commits July 12, 2022 14:29

docs: Added all terms out of the spi topic area into the terminology

6924781

docs: Added all terms out of the discussion area on GitHub into the t…

4f1e3ca

…erminology

docs: add information to the entries

a7ce2e2

docs: improved writing style and changed text for connector and typem…

0eabb6f

…anager

docs: update changelog

cda989b

janpmeyer requested a review from juliapampus as a code owner July 12, 2022 12:50

github-actions bot added this to In progress in Connector Jul 12, 2022

paullatzelsperger self-requested a review July 12, 2022 14:04

paullatzelsperger reviewed Jul 12, 2022

View reviewed changes

docs: updated and deleted entries in cause of suggestion in the pull …

7c5ceca

…request

github-actions bot added the stale Open for x days with no activity label Jul 21, 2022

github-actions bot closed this Jul 29, 2022

Connector automation moved this from In progress to Done Jul 29, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(terminology): extended and updated terminology #1653

docs(terminology): extended and updated terminology #1653

janpmeyer commented Jul 12, 2022

paullatzelsperger left a comment •

edited

paullatzelsperger Jul 12, 2022

janpmeyer Jul 12, 2022

paullatzelsperger Jul 12, 2022

janpmeyer Jul 12, 2022

paullatzelsperger Jul 12, 2022 •

edited

janpmeyer Jul 12, 2022

paullatzelsperger Jul 12, 2022

paullatzelsperger Jul 12, 2022

janpmeyer Jul 12, 2022 •

edited

paullatzelsperger Jul 12, 2022 •

edited

janpmeyer Jul 12, 2022

paullatzelsperger Jul 12, 2022

jimmarino commented Jul 13, 2022 •

edited

github-actions bot commented Jul 21, 2022

github-actions bot commented Jul 29, 2022

docs(terminology): extended and updated terminology #1653

docs(terminology): extended and updated terminology #1653

Conversation

janpmeyer commented Jul 12, 2022

What this PR changes/adds

Why it does that

Linked Issue(s)

Checklist

paullatzelsperger left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paullatzelsperger Jul 12, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

janpmeyer Jul 12, 2022 • edited

Choose a reason for hiding this comment

paullatzelsperger Jul 12, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jimmarino commented Jul 13, 2022 • edited

github-actions bot commented Jul 21, 2022

github-actions bot commented Jul 29, 2022

paullatzelsperger left a comment •

edited

paullatzelsperger Jul 12, 2022 •

edited

janpmeyer Jul 12, 2022 •

edited

paullatzelsperger Jul 12, 2022 •

edited

jimmarino commented Jul 13, 2022 •

edited