Documentation of extensions

[florianrusch-zf]

Hi all together,

I'm thinking about how we can improve the documentation of the extensions. The idea would be to have some kind of template or pattern of points and headlines that should be considered in the README.md of each extension.

E.g. something like this:

• General description
• Usage/Examples
  • At least the code for the build.gradle.kts <= We should do this because some extensions don't have matching artifact and folder names, which sometimes leads to confusions.
• (Optional) Configurations
  • Table of all configurations introduced by this specific extension (non-transitiv)
  • Mark mandatory configurations
  • Display default values and a description
• (Optional) REST/API Endpoint descriptions (Might be better to add via Swagger?)
• (Optional) Limitations/restrictions of the extension
• (Optional) Reference to further/other documentations (e.g. for the observability extensions it might be useful to reference to the overall documentation)

Another point I would like to discuss: I think a list with all extensions would help a lot of people to identify what the EDC can and can't do. Also in terms of the onboarding, it would help lot of people understand how the EDC works and where to dig deeper if they need something. However, I don't think a manually maintained list is the way to go...does anyone have an idea how we can automate this? Of course we could create a script that parses all README.md files from the extensions/ folder and so on, but I think this solution is also not the right way and relatively error prone. What do you think? Does anyone have another idea?

\cc @akelecevic @alexandrudanciu because I think you both already had a look at the documentation of the extensions

[DominikPinsel]

Looks good. Maybe we can also add a list of the required and provided interfaces, so that its not necessary to look through the ServiceExtension implementations when adding new extensions.

Additionally we could update the extension section in architecture-principles, too.

VII. Extensions and Libraries
1. Extension modules contribute a feature to the runtime such as a service.
2. SPI modules define extensibility points in the runtime. There is a core SPI module that defines extensibility for essential runtime features. There are other SPI modules that define extensibility points for optional features such as IDS.
3. Libraries are utility modules that provide classes which may be used by other modules. They do not directly contribute features to the runtime.
4. An SPI module may only reference other SPI modules and library modules.
5. An Extension module may only reference other SPI modules and library modules.
6. A library module may only reference other library modules.

Things we should add there are

• library modules should end with -lib
• spi modules should end with -spi
• libary modules should be placed next to the extensions, that are using them. So somewhere in extensions/.... If this is not possible the libraries should be places in /commons

_{Dominik Pinsel dominik.pinsel@daimler.com, Daimler TSS GmbH, legal info/Impressum}

[florianrusch-zf]

Maybe we can also add a list of the required and provided interfaces, so that its not necessary to look through the ServiceExtension implementations when adding new extensions.

Good point, but I don't think I would do that. Adding the interfaces to the README.md would mean that we have to update both places when we change/update the extension, which in my experience will eventually lead to the documentation being out of date. :-/ Besides, it is not sooo complicated to have a look into the ServiceExtension class to find out which interfaces have to be there etc. Furthermore, we have the Usage/Example section where something like that could be placed in:

dependencies(
	api("implements-an-interface")
    api("current-extensions-which-uses-interface")
)

But I am absolutely open for other opinions. Maybe the others see it like you do, then we can gladly include it.