[Documentation] Feedback Documentation

[DanielOber]

Relevant documentation

Die Docs für die Refarch-Templates sind hier zu finden: https://refarch-templates.oss.muenchen.de/
und die allgemeinen docs für die Refarch hier: https://refarch.oss.muenchen.de/

Problem description (optional)

Ccollection of feedback on the refarch documentation

Desired solution

Revision of the documentation

Additional context (optional)

No response

No duplicate

• I confirm that this issue is not a duplicate

Code of Conduct

• I agree to follow this project's Code of Conduct

[hupling]

Feedback:

• Design: Vielleicht ist das auch nebensächlich, aber es erinnert mich nicht an die Stadt München

• Integrations S3/Address/Cosys/Dms/Email irgendwie ist hier auch die Config beschrieben, aber mir fehlen konkrete Code Beispiele.

• Cosys: Wie funktioniert das bei der LHM? Also muss ich jetzt an zwei Stellen in github und gitlab schauen, damit ich weiß wie das funktioniert. Wie lauten die interne Cosys-URLs etc.? Werden dann die internen Libraries auf deprecated gesetzt und hier auf die neue Doku verwiesen?

[vjohnslhm]

Ich finde es beim ersten Lesen etwas verwirrend, dass es zwei verschiedene Dokumentationen gibt. Wenn ich mich noch nicht groß mit der RefArch befasst hätte, wüsste ich erst mal nicht in welcher ich suchen muss um Infos zu bekommen. Alle Infos an einem Ort zu finden wäre da schöner.

[mirrodi]

Die Verlinkung führt zu https://opensource.muenchen.de/impress.html, was nochmal eine komplett andere Seite ist, von der man nicht mehr auf die RefArch Seite kommt.

[boal]

Die Dokumentation ist aufgeteilt in die allgemeine Refarch-Doku (https://refarch.oss.muenchen.de/) und eine Doku für die Templates (https://refarch-templates.oss.muenchen.de/).

Auf der Refarch-Seite wird auf der Startseite neben dem Gateway, den Integrations, ... auf dieTemplates verweisen. Bei Menüpunkt "Docs" ist jedoch nichts zu den Templates zu finden.

Wäre es ggf. nicht besser die beiden Dokus zu einer zusammenzuführen und die Refarch-Templates als eigenen Menüpunkt oder auf der Dokuseite als eigenes Kapitel in Refarch zu integrieren.

z.B. als eigenes Kapitel Templates neben dem Kapitel Integrations.

[hupling]

@boal das ganze SPS wird auch irgendwie ausgelagert. Ich weiß auch nicht warum.

[hupling]

@udobrmuc wollte etwas über die Konfig von Keycloak wissen. Dazu gibt es auch keine Infos wie man die Keycloak Instanz konfigurieren kann

[devtobi]

Ergebnisse Besprechung vom 26.03.2025:

• Design: Wir passen das Design nicht an muenchen.de an. Wir haben uns an opensource.muenchen.de orientiert. Damit ist das Design Veranwortung vom OSPO (siehe https://git.muenchen.de/ccse/ospo/-/issues/581). Sollte es künftig ein zentrales Theme geben, können wir gerne darauf umsteigen.
• Codebeispiele für Integrations: Dein Einwand an sich ist korrekt, Codebeispiele sind hier definitiv sinnvoll. Hier gibt es aber noch Unklarheiten, wie die Integrations künftig aussehen und geschnitten werden, werden wir hier erstmal keine weitere Zeit in die Dokumentation investieren. => Als Übergangslösung werden wir in der Doku darauf hinweisen.
• Dokumentation für externe Systeme: Wir wollen hier keine zusätzliche Dokumentation in der RefArch platzieren. Denkbar wäre es aber zusätzliche Links auf interne Dokumentation anzubieten. Verlinken von public Doku zu non-public Doku ist in https://git.muenchen.de/ccse/ospo/-/issues/589 abgeklärt. Aufgrund der Unklarheiten (siehe Punkt davor) müssen wir hier aber auch noch abwarten.
• Umzug der Dokumentation: Wir werden die Dokumentation der RefArch-Templates nach https://refarch.oss.muenchen.de umziehen. In den Templates wird dann nur noch ein Minimalbeispiel abgelegt. Außerdem werden die READMEs aktualisiert und internen Links.
• Externes Impressum: Wir würden das Impressum gerne extern belassen, um den Pflegeaufwand zu vermeiden. Impressum wird vermutlich eh selten angesteuert. @klml Ist das so von deiner Seite aus in Ordnung? Passt das rechtlich so?
• Umzug SPS-Dokumentation: Das Thema wollen wir künftig nocheinmal diskutieren, da die SPS ein Querschnittsthema darstellt und daher nicht unbedingt nur für die RefArch relevant ist. Daher wäre auch eine getrennte Dokumentation angebracht.
• Keycloak Dokumentation: Alle Thematiken im Zusammenhang mit KeyCloak werden wir nicht dokumentieren. Hier ist auf die KeyCloak-Doku zu referenzieren. Wir haben hier schon Tickets ([Documentation] Add differnt ways of using keycloak security #468, [Bug] Keycloak permissions mapper missing refarch-templates#882) und andere Abhängigkeiten wie Keycloak-Plugins und Add organization creation feature and Linux doc fix mayope/keycloakmigration#100. Diese müssen noch gelöst werden.

TODOs:

• Umzug der Dokumentation der refarch-templates nach refarch

Danke an alle für das Lesen der Dokumentation und das konstruktive Feedback! 😄

[klml]

@klml Ist das so von deiner Seite aus in Ordnung?

Passt!

[hupling]

also ich habe das Problem schon per Webex an @simonhir gemeldet:

Ich hatte Probleme im Backend Postgress zu konfigurieren. Natürlich war es mir dann klar wie es geht, nachdem mir die Datei https://github.com/it-at-m/refarch-templates/blob/main/refarch-backend/src/main/resources/application-local.yml#L11 geschickt wurde. Allerdings habe ich in der application.yml gesucht oder eine Readme im Backend Ordner erwartet. Auf der Doku-Webseite habe ich auch keine Config Anleitung gefunden.

Also beim Formular-Server habe ich eine Woche gedebuggt, weil ich an der falschen Stelle bei der EAI das Passwort gesetzt hatte.

[DanielOber]

also ich habe das Problem schon per Webex an @simonhir gemeldet:

Ich hatte Probleme im Backend Postgress zu konfigurieren. Natürlich war es mir dann klar wie es geht, nachdem mir die Datei https://github.com/it-at-m/refarch-templates/blob/main/refarch-backend/src/main/resources/application-local.yml#L11 geschickt wurde. Allerdings habe ich in der application.yml gesucht oder eine Readme im Backend Ordner erwartet. Auf der Doku-Webseite habe ich auch keine Config Anleitung gefunden.

Also beim Formular-Server habe ich eine Woche gedebuggt, weil ich an der falschen Stelle bei der EAI das Passwort gesetzt hatte.

Warum hattest du die application-local.yml nicht und warum musste dir die zugeschickt werden?

[hupling]

Warum hattest du die application-local.yml nicht und warum musste dir die zugeschickt werden?

Ich hatte schon die application-local.yml, aber woher soll ich wissen, dass dort die gesamte Konfig drin ist. Ich hatte nur in der application.yml geschaut. Beim KPS haben wir dort alle Konfig drin, auch teilweise auskommentiert, damit man weiß was es alles gibt.

[devtobi]

Würde es dir weiterhelfen, wenn du ein Helm-Chart mit entsprechendem Beispiel hättest? Da arbeiten wir ja noch gerade dran. Wo siehst du einen Vorteil mit einer Übersicht über die Konfiguration in der RefArch Doku?