Ideas how to improve documentation and comprehensibility of the code

[dsmf]

Explain terms on first use and in glossary and also add synonyms

Missing:

• AAS
• Catalog = EDC Catalog = ...
• Contract offer = Catalog Item = ... (synonyms were added and mutually linked, but definition still missing)
• DigitalTwinRegistryKey
• EDC Provider
• EDR Token = EndpointDataReference = ...
• Shell
• Shell Descriptor = ...
• Submodel
• Tombstone
• Depth parameter is not explained

hi! was diving a bit on IRS and bumped into the "depth" config, something I tried to debug, but still a bit unclear, what is the purpose of this on IRS world?´

Integer Max depth of the item graph returned. If no depth is set, the item graph with max depth is returned. The depth parameter defines the depth of the item graph to be returned. In case of an iterative scenario, this defined the number of hops the irs traverses through the part or supply chain. Depth 2 means that from an OEM perspective, the item graph is expanded until tier level 2.

High-level description of Business Context, Components, Flows

• Add some short description what IRS is in business context at the beginning of the ARC42 documentation

Or refer to the README

• https://github.com/eclipse-tractusx/item-relationship-service/blob/main/README.md#vision-and-mission-statement

• https://github.com/eclipse-tractusx/item-relationship-service/blob/main/README.md#what-is-the-irs

• The chapter "Introduction and goals" says "This chapter gives you an overview about the goals of the service, in which context the service runs and which stakeholders are involved.", but there is no description of stakeholders...

• Under ARC42 Documentation in section "Structure", briefly describe the 4 components to give the reader a better understanding of the main responsibilities of each component.

• ARC42: Describe the two different IRS flows (iterative, recursive) and describe when each is relevant.

Improve documentation structure

• Move section "IRS API" to Runtime view
  - Currently it is in "Building block view", but I don't think it belongs there.

• Increase depth of TOC section levels to at least 3

  • ToC shows only two levels. Increase this to get a better overview.
  • Probably this is the reason why some headings are on same level that should be one level lower (because if we move them one level down they disappear from ToC with our current settings).
  • Example for this is:
    • Runtime View
      • IRS iterative
      • ... these sections here should be subsections of IRS iterative ...
      • IRS recursive
      • ... these sections here should be subsections of IRS recursive ...

Improve documentation of application usage

• Describe how to create a job

  • Request body with its various parts and meaning.
  • Response body with its various the meaning of the concrete results on an example.

• Add the links to OpenAPI specification, stored version and test:

  • There is the following sentence: "The generated OpenAPI specification file is automatically compared to a fixed, stored version of it to avoid unwanted changes of the API." https://eclipse-tractusx.github.io/item-relationship-service/docs/arc42/full.html#_business_context
    • Add link to the generated OpenAPI specification here
    • Add code reference to the stored version here
    • Add code reference to the test that compares these here

• Improve description of testdata under local/testing/testdata (the README only describes the script, not the test data).

Add code references in documentation

• UML diagrams

  • Enhance UML sequence diagrams with code comments that include a reference to the actual class and method called (this way it will not be visible in the documentation itself but visible for developers).

• Tests

  • Add code references to important tests that help with understanding. This provides a better connection between code and documentation especially for new developers.
  • Testautomatisation for local development and CI/CD pipeline using mocks #344
  • ...

Explain difficult to understand code places

• Describe how the connection between EdcEndpointReferenceRetriever - edcSubmodelFacade works (DefaultConfiguration)
  • explain why there is so much abstraction, see injected lambda in DefaultConfiguration or if it is not needed, remove it, because this makes the code very hard to understand for the uninitiated

Improve how to contribute documentation

• Add documentation how to create a release
• Add documentation how to create a helm release (release-chart-7.0.1 - fix rename irs helm chart #548)

Automate keeping documentation up to date

• Add a broken link checker to GitHub workflow

  • in order to keep links in documentation up to date
  • see https://github.com/marketplace/actions/broken-link-checker-action
  • evaluate whether this also checks internal relative links

• Keep Kubernetes version in sync

  • we have a workflow that checks latest three versions
  • but in charts/irs-helm/README.md the version is hardcoded and needs to be kept in sync manualls (find a way to avoid duplicate maintenance of the version)

[dsmf]

Add link to https://eclipse-tractusx.github.io/docs-kits/kits/Data%20Chain%20Kit/Adoption%20View%20Data%20Chain%20Kit/ in readme too? (already linked in FAQ)

[dsmf]

we should align the above list with #408

[dsmf]

Improve sprint role description, see #541