docs: provide documentation templates

[juliapampus]

What this PR changes/adds

Adds templates for documenting decision records, extensions, and launchers.

Why it does that

Would be nice if the documentation files followed the same structure. Furthermore, it makes it easier for developers to add necessary information.

Further notes

--

Linked Issue(s)

Closes #1291

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? (take a look at the CONTRIBUTING and styleguide for details)

[alexandrudanciu]

Thank you for the contribution. I've added some minor remarks.

[paullatzelsperger]

A few suggestions directly in the code.

[MoritzKeppler]

Left some minor comments but nothing that necessarily needs to be changed before merging. Fine with it as it is. Thanks, Julia!

[eclipse-edc-bot]

Can one of the admins verify this patch?

[florianrusch-zf]

Looks very good and I just have some minor suggestions 😉

[jimmarino]

I don't think we should document extensions or launchers individually and prefer to document artifacts such as interfaces and dependencies either in code or via Gradle:

1. The information will get out of sync and become a maintenance burden
2. End-users don't need this level of detail. Developers will need to look at code for this level of detail anyway.

Instead, how about documenting things such as features (aggregations of modules such as SQL or Cosmos persistence) via descriptive markdown that points to BOM coordinates? Launchers could be documented in a similar way. Enforce interface documentation on the class artifacts themselves.

[juliapampus]

I don't think we should document extensions or launchers individually and prefer to document artifacts such as interfaces and dependencies either in code or via Gradle:

1. The information will get out of sync and become a maintenance burden
2. End-users don't need this level of detail. Developers will need to look at code for this level of detail anyway.

Instead, how about documenting things such as features (aggregations of modules such as SQL or Cosmos persistence) via descriptive markdown that points to BOM coordinates? Launchers could be documented in a similar way. Enforce interface documentation on the class artifacts themselves.

What do the others think? @alexandrudanciu @MoritzKeppler @paullatzelsperger @ronjaquensel @ndr-brt

[ronjaquensel]

I don't think we should document extensions or launchers individually and prefer to document artifacts such as interfaces and dependencies either in code or via Gradle:

1. The information will get out of sync and become a maintenance burden
2. End-users don't need this level of detail. Developers will need to look at code for this level of detail anyway.

Instead, how about documenting things such as features (aggregations of modules such as SQL or Cosmos persistence) via descriptive markdown that points to BOM coordinates? Launchers could be documented in a similar way. Enforce interface documentation on the class artifacts themselves.

What do the others think? @alexandrudanciu @MoritzKeppler @paullatzelsperger @ronjaquensel @ndr-brt

I would prefer to have documentation on how to setup/configure/use a certain extension/launcher in the respective modules' READMEs. That way, they're easy to find and people don't have to look for them in the code or elsewhere. I've already had this problem when trying out new features and had to go through the classes step by step as well as look at tests, which took up quite a lot of time. I think a central README holding all that information would be very helpful.

@jimmarino what do you mean by via descriptive markdown that points to BOM coordinates? Since the READMEs are also Markdown, couldn't we also add the BOM references to them?

[alexandrudanciu]

I don't think we should document extensions or launchers individually and prefer to document artifacts such as interfaces and dependencies either in code or via Gradle:

1. The information will get out of sync and become a maintenance burden
2. End-users don't need this level of detail. Developers will need to look at code for this level of detail anyway.

Instead, how about documenting things such as features (aggregations of modules such as SQL or Cosmos persistence) via descriptive markdown that points to BOM coordinates? Launchers could be documented in a similar way. Enforce interface documentation on the class artifacts themselves.

What do the others think? @alexandrudanciu @MoritzKeppler @paullatzelsperger @ronjaquensel @ndr-brt

I acknowledge the use case of end-users writing custom launchers and having to pick relevant extensions from a plethora of possible options. Documentation for each extension would definitely help. If this documentation is not provided within the module, then it could be consolidated within a central decision matrix. This, however, would get obsolete very soon.

[paullatzelsperger]

removed myself as reviewer, as I don't have the bandwidth ATM and don't want to block the PR.

[ndr-brt]

I don't think we should document extensions or launchers individually and prefer to document artifacts such as interfaces and dependencies either in code or via Gradle:

1. The information will get out of sync and become a maintenance burden
2. End-users don't need this level of detail. Developers will need to look at code for this level of detail anyway.

Instead, how about documenting things such as features (aggregations of modules such as SQL or Cosmos persistence) via descriptive markdown that points to BOM coordinates? Launchers could be documented in a similar way. Enforce interface documentation on the class artifacts themselves.

What do the others think? @alexandrudanciu @MoritzKeppler @paullatzelsperger @ronjaquensel @ndr-brt

I think the modules README should contain some basic information on how to use the module and details about configuration (that could become automatically compiled with #1323 ), but no other details (that should be left into the code)

[juliapampus]

As I see now, the majority of people (that interacted with the PR) support the idea of having templates. I will merge this now. As soon as we see that they may be too restrictive or detailed, we can definitely adjust them.

Details should be definitely added as Javadocs or in the gradle files. However, every module should come with a markdown providing basic information.