search

OPUS4 / userdoc

User manual for OPUS 4.
https://opus4.github.io/userdoc
1 stars 12 forks source link

Einheitliche Regeln für die Dokumentation von Konfigurationsparametern #107

Open j3nsch opened 2 years ago

j3nsch commented 2 years ago

Die Dokumentation von Konfigurationsparametern wird zum Teil unterschiedlich gehandhabt. Hier z.B. ein Hinweis.

So richtig gefällt mir das nicht. Im Prinzip gehört diese Beschreibung als Unterkapitel von Kapitel 7 "Parameter der Config.ini". Dort haben wir schon verschiedenste Möglichkeiten beschrieben, Parameter zu definieren, für jeden Parameter irgendwie anders:

  1. Parameter ist bereits in der config.ini enthalten und muß nur aktiviert / geändert werden.
  2. Parameter ist in der config.ini.template enthalten und muß von dort kopiert werden in die config.ini.

Diese beiden Fälle 1. und 2. verstehe ich und finde sie in Ordnung. Die Fälle 3. und 4. finde ich nicht dagegen problematisch:

  1. Parameter ist aus der application.ini zu kopieren und in die config.ini einzutragen.
  2. Parameter ist nirgends vorhanden und muß neu eingefügt werden in die config.ini.

Warum wird das so unterschiedlich gehandhabt?

Auch Kapitel 6.2 "Config.ini anlegen" finde ich nicht wirklich erhellend: "OPUS4 liefert eine config.ini.template mit aus. Diese Datei liegt unter $BASEDIR/opus4/application/configs und muss nach ihrer Bearbeitung auch wieder dort gespeichert und die Endung 'template' entfernt werden.In der config.ini müssen die Werte für lokale Gegebenheiten definiert werden, ohne die OPUS4 nicht lauffähig ist. Alle Werte, die in der config.ini definiert werden, überschreiben die entsprechenden Werte in der application.ini, weshalb nicht nur zusätzliche, sondern immer alle gewünschten Werte in die config.ini geschrieben werden müssen."

Intern: https://tickets.zib.de/jira/browse/OPUSVIER-3357

j3nsch commented 2 years ago

Im Rahmen der Umstellung auf Laminas wird sich das Konfigurationssystem ändern und damit werden Anpassungen an der Dokumentation notwendig werden. Die Parameter werden weiter existieren, aber wahrscheinlich in andere Dateien oder die Datenbank verlagert.

Ursprünglicher Kommentar:

Die Frage ist hier, wollen wir wirklich alle Parameter in der config.ini haben? Nicht alle Parameter müssen einen Defaultwert haben, der dann in der application.ini steht. Manche Parameter können vorhanden sein oder eben nicht. Ich denke es hängt davon ab wie häufig der Parameter verwendet wird. Ansonsten halte ich es für legitim in der Dokumentation zu schreiben, dass ein Eintrag zu Konfiguration hinzugefügt werden muss.

Prinzipiell ist unser Konfigurationssystem aber "nicht unproblematisch" und sollte überdacht werden. Das geht aber über die Dokumentation hinaus und ist ein aufwendigeres Projekt.

j3nsch commented 2 years ago

Der Text in Kapitel 6.2 erscheint mir auch nicht besonders hilfreich. Wir sollten im Rahmen der Online Dokumentation schrittweise an Aktualisierungen arbeiten.