Skip to content

Commit 05af5e4

Browse files
juliapampusjuliapampus
authored
docs: restructure documentation (#1307)
* chore: move documentation files to subfolders * chore: restructure toc of documentation directory * docs: update documentation * docs: update CHANGELOG.md * chore: apply feedback
1 parent 8f13348 commit 05af5e4

File tree

109 files changed

+610
-175
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

109 files changed

+610
-175
lines changed

Diff for: ‎CHANGELOG.md

+1
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ in the detailed section referring to by linking pull requests or issues.
1414
* Bugfixing DataManagementApi
1515
* Build improvements
1616
* Improvements to Dependency Resolution
17+
* Improve and extend documentation
1718

1819
### Detailed Changes
1920

Diff for: ‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ Contains several scripts to deploy a connector in an AKS cluster on Microsoft Az
139139
## Code style & Patterns
140140

141141
Please refer to the dedicated [style guide](styleguide.md) and the patterns we documented
142-
in [architecture principles](docs/architecture-principles.md).
142+
in [architecture principles](docs/architecture/architecture-principles.md).
143143

144144
## Roadmap
145145

Diff for: ‎core/micrometer/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
# Micrometer extension
22

3-
See [developer documentation](../../docs/metrics.md)
3+
See [developer documentation](../../docs/developer/metrics.md)

Diff for: ‎data-protocols/ids/README.md

-8
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,3 @@
1-
**Please note**
2-
3-
### Work in progress
4-
5-
All content reflects the current state of discussion, not final decisions.
6-
7-
---
8-
91
# IDS
102

113
This IDS extension represents a collection of all IDS extensions, that are required to run an IDS connector.

Diff for: ‎data-protocols/ids/ids-api-multipart-endpoint-v1/README.md

-8
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,3 @@
1-
**Please note**
2-
3-
### Work in progress
4-
5-
All content reflects the current state of discussion, not final decisions.
6-
7-
---
8-
91
# IDS Multipart API
102

113
## Configuration

Diff for: ‎data-protocols/ids/ids-spi/README.md

+1-9
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,3 @@
1-
**Please note**
2-
3-
### Work in progress
4-
5-
All content reflects the current state of discussion, not final decisions.
6-
7-
---
8-
91
# IDS SPI
102

113
## IDS Asset Property
@@ -14,4 +6,4 @@ All content reflects the current state of discussion, not final decisions.
146
|:---|:---|:---|
157
| ids:fileName | Artifact.FileName | Name of the Artifact file |
168
| ids:byteSize | Artifact.ByteSize | Size of the Artifact in bytes |
17-
| ids:fileExtension | Representation.MediaType.FileExtension | Suffix of a file name, indicating the nature and intended processing of the file |
9+
| ids:fileExtension | Representation.MediaType.FileExtension | Suffix of a file name, indicating the nature and intended processing of the file |

Diff for: ‎docs/Architecture.md

-8
This file was deleted.

Diff for: ‎docs/README.md

+132-14
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,149 @@
11
# Eclipse Dataspace Connector
22

3-
**Please note**: Work in progress. All content reflects the current state of discussion, not final decisions.
3+
**Please note**: Work in progress. All content of provided documentation reflects the current state of discussion.
44

55
## Overview
66

7-
TBD
7+
Data spaces allow organizations to securely share data with others. They enable data cooperation in a multi-cloud
8+
federation by focusing on identity, trust, sovereignty, and interoperability.
89

9-
## Configuration
10+
- Identity: Each participant remains in control of their identity.
11+
- Trust: Each participant decides who to trust.
12+
- Sovereignty: Each participant decides under what policies their data is shared.
13+
- Interoperability: Each participant remains in control of their deployment.
1014

11-
TBD
15+
Since the concept of data spaces is emerging and promises new capabilities to the data exchange between participants
16+
(organizations) in terms of data sovereignty, many may ask the questions "What is a connector?" and "When and why should
17+
I use it?".
1218

13-
## Installation
19+
**What is a connector?**
1420

15-
TBD
21+
A participant in a data space wants to share and consume data offers, transfer data, and - most important - maintain
22+
control over its usage. All processes are based on the aforementioned principles of identity, trust, sovereignty, and
23+
interoperability. This is why a connector component is used to participate in a data space and mainly focuses on
24+
these aspects while ensuring data sovereignty along the entire data supply and value chain.
1625

17-
## Troubleshooting
26+
In order to build up and participate in a data space, it is not enough to consider existing communication protocols.
27+
This means, besides the actual data transfer, a connector has to provide capabilities, i.e., for discovering,
28+
connecting, automated contract negotiation, policy enforcement, and auditing processes. Data space connectors act as
29+
logical gatekeepers that integrate into each participant’s infrastructure and communicate with each other.
1830

19-
TBD
31+
**When to use a data space connector?**
2032

21-
## Architecture
33+
A connector should be used each time the controlling (legal) entity of the data changes. A connector provides a
34+
generic way to express, negotiate, and document the rules under which data is shared, and also with whom. Not just
35+
in plain text but machine-readable and technically enforceable.
2236

23-
[Architecture Principles](architecture-principles.md)
37+
Existing open-source projects address the technical challenges of cataloguing and transferring data for a wide
38+
range of use cases. However, there is no open-source effort aimed at providing an interoperable, cross-organization
39+
framework for data sharing that is built on a common identity model and uniform policy enforcement. This project
40+
will integrate with existing data exchange technologies and provide these missing pieces to create a system for data
41+
sharing where each organization is able to exert control over how its shared data is used.
2442

25-
[Sequence Diagrams](architecture/README.md)
43+
**About the Eclipse Dataspace Connector**
2644

27-
[Domain Model](domain-model.md)
45+
A data-sharing system requires a protocol implementation for policy enforcement among participants. The EDC will
46+
implement the International Data Spaces (IDS) standard as well as relevant protocols and requirements associated
47+
with Gaia-X, and thereby provide implementation and feedback to these initiatives. However, the EDC will be
48+
extensible in a way that it may support alternative protocols.
49+
Its added value is achieved through the separation of control and data plane, which enables a modular and
50+
thereby customizable way to build data spaces. Due to common interfaces and mapping of existing standards, the EDC
51+
adds capabilities of contract negotiating and policy handling in an interoperable manner.
2852

29-
## Terminology
53+
**Open, community-driven and extensible**
3054

31-
see [Terminology](Terminology.md)
55+
As an open source project hosted by the Eclipse Foundation, the EDC provides a growing list of modules for many
56+
widely-deployed cloud environments (AWS, Azure, GCP, OTC, etc.) "out-of-the-box" and can easily be extended for
57+
more customized environments, while avoiding any intellectual property rights (IPR) headaches.
58+
59+
![EDC Capabilities](_media/edc-overview.png)
60+
61+
### How to get started
62+
63+
According to the [Eclipse Foundation Development Process](https://www.eclipse.org/projects/dev_process/#2_3_Three_Communities),
64+
each person that interacts with and is interested in an Eclipse Foundation project can be assigned to specific roles: developers,
65+
users, and adopters. This documentation addresses all of them by defining explicit sections, next to the general information
66+
and overviews. Depending on your interests, you can take a look at one or more of the following.
67+
68+
- **Adopter**: Adopters are the individuals and organizations that adopt Eclipse technology for inclusion in their own products and services.
69+
- **Developer**: Developers are committers or contributors. A contributor is anybody who makes contributions to a project. A
70+
committer is a software developer who has the necessary rights to make decisions regarding a Project.
71+
- **User**: Users use the project to realize use cases. They do not want to contribute code or customize the software; they want
72+
to use it as-is. Users provide valuable feedback and proof that a project is useful and needed.
73+
74+
No matter what role you assign yourself to, if you want to become familiar with the EDC and its functionalities,
75+
please take a look at our [hands-on](overview/hands-on.md) section and samples.
76+
77+
### How to contribute
78+
79+
All developments follow the [principles defined by the Eclipse Foundation](https://www.eclipse.org/projects/handbook/#preamble-principles).
80+
* Transparency: A project’s discussions, minutes, deliberations, project plans, plans for new features, and other
81+
artifacts are open, public, and easily accessible.
82+
* Openness: The project is open to all. Everyone has the same opportunities; everyone participates with the same rules.
83+
* Meritocracy: The more that somebody contributes, the more responsibility they will earn.
84+
* Vendor-neutrality: No vendor is permitted to dominate a project, and nobody can be excluded from participating
85+
in a project based on their employment status.
86+
87+
If you want to know more about actually contributing code, please find more information [here](./_helper/contributing.md)
88+
and take a look at our [developer documentation](./developer/README.md).
89+
90+
> To join our Discord server, you may use [this](https://discord.gg/n4sD9qtjMQ) invite.
91+
Details about our biweekly open Q&A session can be seen [here](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/discussions/1303).
92+
93+
## Statement: EDC vs DSC
94+
95+
_Also to be read on [GitHub](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/discussions/1037)._
96+
97+
**The Eclipse Dataspace Connector (EDC) expands and improves the Dataspace Connector (DSC) as a follow-up development
98+
by an OSS community that is being contributed to the various initiatives that are involved in building data spaces.
99+
Both connectors do _not_ have the same codebase, but follow the same ideas of sovereign data spaces.**
100+
101+
The DSC is a component previously developed by Fraunhofer ISST. The goal was to build an IDS-compliant connector
102+
driven by a community (e.g., from initiatives as Catena-X, Gaia-X, Mobility Data Space) as OSS to foster distribution
103+
and usage. While some discussions with several partner organizations begin/mid last year, it became very clear that
104+
the underlying governance and rules for contributions did not fit the requirements to form such a community and work
105+
on the code together due to questions regarding intellectual property (IP), licensing, etc.
106+
107+
As a solution, partners agreed in June '21 to create a project within the Eclipse Foundation (EF), since EF provides
108+
clear governance structures and rules allowing exactly the collaboration and community building, it was aimed for.
109+
While the transfer process and meetings with initial committers (among others), the architecture was rethought to
110+
directly address future requirements in terms of applicability, robustness, scaling, etc. A much-discussed issue
111+
dealt with the limitation to a single data protocol such as the IDS vs. a solution that can support multiple such
112+
protocols. The decision fell on the latter and so the EDC is now developed based on a new architecture and design
113+
principles but based on available parts (like the DSC) that were transferred as initial contributions to the EF
114+
(see the [project's proposal](https://projects.eclipse.org/proposals/eclipse-dataspace-connector)). This time
115+
with a [community of various companies](https://projects.eclipse.org/projects/technology.dataspaceconnector/who)
116+
that bring in requirements from different initiatives like Catena-X, Eona-X, IDSA, Gaia-X, or MDS, and work on
117+
a decentralized data space implementation based on a data space connector that provides capabilities for data
118+
exchange and extensibility to various shared service implementations (catalog, identity, usage control, logging, etc.)
119+
through interfaces. Thereby, the EDC can support IDS(A)-based components like the DAPS (Identity), or Metadata Broker
120+
(Catalog) as well as other approaches like WEB-DID (Identity) or Federated Catalog (Catalog). All with the same core
121+
to enable organizations to use a single technology to participate in multiple data spaces/ecosystems/federations in
122+
parallel.
123+
124+
## Correlating projects
125+
126+
**Please note**: Not every project may be mentioned here. If you want to add one, please feel free to open a PR
127+
or provide us with information via an issue.
128+
129+
| Name | Description |
130+
| :--------- | :---------- |
131+
| Gaia-X | The EDC allows organizations to exchange data compliant to rules and policies of the Gaia-X AISBL according to the corresponding Trust Framework |
132+
| Catena-X | Uses the EDC as Connector component to build a data space between participants |
133+
| Tractus-X | Eclipse Foundation OSS project initiated by Catena-X consortia, where specific (Catena-X related) EDC-extensions can be implemented under clear governance and rules |
134+
135+
## Important links
136+
137+
If you want to get more information, besides the one provided here, you may take a look
138+
at the following links:
139+
140+
| Name | Link |
141+
| :--------- | :--- |
142+
| Homepage | <https://dataspace-connector.io/> (in progress) |
143+
| Eclipse project page | <https://projects.eclipse.org/projects/technology.dataspaceconnector> |
144+
| EDC project proposal | <https://projects.eclipse.org/proposals/eclipse-dataspace-connector> |
145+
| YouTube Channel | <https://www.youtube.com/channel/UCYmjEHtMSzycheBB4AeITHg> |
146+
| LinkedIn | in progress |
147+
| Main Repository | <https://github.com/eclipse-dataspaceconnector/DataSpaceConnector> |
148+
| Documents & presentations | <https://github.com/eclipse-dataspaceconnector/Collateral> |
149+
| Publications | <https://github.com/eclipse-dataspaceconnector/Publications> |

Diff for: ‎docs/_helper/contributing.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[remoteMarkdownUrl](https://raw.githubusercontent.com/eclipse-dataspaceconnector/DataSpaceConnector/main/CONTRIBUTING.md)
2+
3+
_Directory link: [contributing.md](../../CONTRIBUTING.md)_

Diff for: ‎docs/_helper/openapi.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[remoteMarkdownUrl](https://raw.githubusercontent.com/eclipse-dataspaceconnector/DataSpaceConnector/main/openapi.md)
2+
3+
_Directory link: [openapi.md](../../openapi.md)_

Diff for: ‎docs/_helper/styleguide.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[remoteMarkdownUrl](https://raw.githubusercontent.com/eclipse-dataspaceconnector/DataSpaceConnector/main/styleguide.md)
2+
3+
_Directory link: [styleguide.md](../../styleguide.md)_

Diff for: ‎docs/_media/edc-overview.png

104 KB
Loading

Diff for: ‎docs/_sidebar.md

+22-42
Original file line numberDiff line numberDiff line change
@@ -2,48 +2,28 @@
22
landing page of this section. Other subsections are placed below and can be linked separately. Feel
33
free to add sections and subsections to this sidebar.)
44

5-
- [Home](README.md)
6-
- [Hands-on](samples.md)
5+
[comment]: <> (Html instead of markdown due to known issues: https://github.com/docsifyjs/docsify/issues/850
6+
and https://github.com/docsifyjs/docsify/issues/1139)
77

8-
- Architecture
9-
- [Overview](architecture/README.md)
10-
- [Configuration](architecture/configuration.md)
11-
- [Contracts](architecture/contracts.md)
12-
- [Data Flow](diagrams/data-flow/README.md)
13-
- [Domain Model](domain-model.md)
14-
- [Policies](Policies.md)
15-
- [Principles](architecture-principles.md)
16-
- [Terminology](Terminology.md)
17-
18-
- IDS
19-
- [Overview](ids/README.md)
20-
- [Architectural Alignment](ids/architectural-alignment.md)
21-
- [Key Components](ids/key-components.md)
8+
- <a href="#/README">Home</a>
229

23-
- Developer
24-
- [Command Queue](command-queue.md)
25-
- [Dependency Resolution](developer/dependency_resolution.md)
26-
- [DPF Selector](developer/dpf_selector.md)
27-
- [DPF Transfer](developer/dpf_transfer.md)
28-
- [Metrics](metrics.md)
29-
- [Release Approach](developer/releases.md)
30-
- [Writing Tests](testing.md)
10+
- Getting Started
11+
- <a href="#/overview/hands-on">First Steps</a>
12+
- <a href="#/adopter/README">Adopter Documentation</a>
13+
- <a href="#/developer/README">Developer Documentation</a>
14+
- <a href="#/user/README">User Documentation</a>
3115

32-
- Decision Records
33-
- [2022-02-03 Integration Testing](developer/decision-records/2022-02-03-integration-testing/README.md)
34-
- [2022-02-07 Micrometer Metrics](developer/decision-records/2022-02-07-micrometer-metrics/README.md)
35-
- [2022-02-07 Tracing](developer/decision-records/2022-02-07-tracing/README.md)
36-
- [2022-02-10 Code Coverage](developer/decision-records/2022-02-10-code-coverage/README.md)
37-
- [Jacoco](developer/decision-records/2022-02-10-code-coverage/jacoco.md)
38-
- [Jacoco with Codacy](developer/decision-records/2022-02-10-code-coverage/codacy.md)
39-
- [Jacoco with Codecov](developer/decision-records/2022-02-10-code-coverage/codecov.md)
40-
- [Jacoco with GitHub Actions](developer/decision-records/2022-02-10-code-coverage/jacoco_github_action.md)
41-
- [Jacoco with Sonarqube](developer/decision-records/2022-02-10-code-coverage/sonarqube.md)
42-
- [2022-02-11 CodeQL](developer/decision-records/2022-02-11-codeql/README.md)
43-
- [2022-02-14 Helm Chart](developer/decision-records/2022-02-14-helm-chart/README.md)
44-
- [2022-03-02 Performance Tests](developer/decision-records/2022-03-02-performance-tests/README.md)
45-
- [2022-03-11 Story Issues](developer/decision-records/2022-03-11-story-issues/README.md)
46-
- [2022-03-15 Policy Scopes](developer/decision-records/2022-03-15-policy-scopes/README.md)
47-
- [2022-03-15 Swagger Annotations](developer/decision-records/2022-03-15-swagger-annotations/README.md)
48-
- [2022-03-30 CosmosDB Lease Mechanism](developer/decision-records/2022-03-30-cosmosdb-lease-mechanism/README.md)
49-
- [2022-04-21 DPF Blob Data Transfer](developer/decision-records/2022-04-21-dpf-blob-data-transfer/README.md)
16+
- General
17+
- <a href="#/architecture/README">Architecture</a>
18+
- <a href="#/architecture/catalog/README">Catalog</a>
19+
- <a href="#/architecture/configuration/README">Configuration</a>
20+
- <a href="#/architecture/data-transfer/README">Data Transfer</a>
21+
- <a href="#/architecture/domain-model">Domain Model</a>
22+
- <a href="#/architecture/identity-management/README">Identity Management</a>
23+
- <a href="#/architecture/ids/README">IDS Standard</a>
24+
- <a href="#/architecture/usage-control/README">Usage Control</a>
25+
26+
- Appendix
27+
- <a href="#/overview/extensions">Extensions</a>
28+
- <a href="#/overview/launchers">Launchers</a>
29+
- <a href="#/overview/terminology">Terminology</a>

Diff for: ‎docs/adopter/README.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Adopter Documentation
2+
3+
Adopters may also want to check out the [user documentation](user/README.md) and [developer documentation](developer/README.md)
4+
as they mainly want to use and integrate the EDC into their own products and services, and therefore need to implement
5+
against existing interfaces while adhering to existing standards and coding style guides.
6+
7+
As an adopter, I want to ...
8+
- ... get an overview of available features and extensions.
9+
- ... get an insight into the roadmap.
10+
- ... integrate the EDC into products and services.
11+
- ... customize the EDC.
12+
- ... write or modify a launcher.
13+
- ... write own extensions.
14+
- ... get an overview of provided interfaces.
15+
- ... implement against existing interfaces.
16+
- ... know what configurations can be applied.
17+
- ... create new configuration properties.
18+
- ... monitor the EDC at runtime.
19+
- ... deal with the deployment of the EDC.
20+
- ... understand the functionalities in detail.
21+
- ... take a look at the codebase.
22+
- ... formulate new requirements.
23+
- ... contribute to the codebase of the OSS.
24+
25+
As an adopter, I do not want to ...
26+
- ... use unstable APIs.
27+
28+
## Important links
29+
30+
- [Contribution guidelines](../_helper/contributing.md)
31+
- [List of extensions](../overview/extensions.md)
32+
- [List of launchers](../overview/launchers.md)
33+
- [OpenApi Documentation](_helper/openapi.md)
34+
- [Samples](../overview/hands-on.md)

0 commit comments

Comments
 (0)