j3nsch
commented
2 years ago Das OPUS 4 Handbuch enthält Tabellen mit den Feldern der Dokumenttypen. Bei Änderungen müssen diese Tabellen angepasst werden. Das wiederspricht dem DRY (Don't Repeat Yourself) Prinzip und lässt sich vermeiden. Die Tabellen können aus dem XML der Dokumenttypen generiert werden, z.B. mit XSLT.
Im Prinzip sollte das automatisch für die Releases erfolgen. Ich denke angestrebt werden, daß der Prozess vollautomatisch ist, die Inhalte also auch nicht manuell ins Wiki kopiert werden müssen. Ich würde die generierten Seiten auf einem öffentlichen Server ablegen, zusammen mit der API Dokumentation und verlinken .
Die Detailseiten zu den Dokumenttypen enthalten eine Auflistung aller Felder mit einer Hervorhebung der Pflichtfelder. Diese Informationen sind im XML der Definitionsdateien für Dokumenttypen enthalten und sollten automatisch generierbar sein, um eine Synchronisation der OPUS 4 Dateien mit der Dokumentation zu vereinfachen.
Es macht vermutlich Sinn Markdown Dateien für Jekyll zu generieren. Das heißt ein Update der Dokumentation könnte mit einem Skript manuell angestossen werden. Das Ergebnis müsste dann manuell committed werden. Evtl. gibt es für solche Anwendungsfälle automatische Möglichkeiten, wie z.B. GitHub Plugins.
Beim Generieren der Seiten sollte auch eine Verlinkung der Feldnamen zu ihren Beschreibungen erfolgen.