Grundlagen der Struktur hinter der Doku
-
Ich bin gebeten worden hier etwas über das Doku-Framework zu schreiben.
Leider bin ich dafür nicht unbedingt der Richtige, da ich mich leider nicht in den Tiefen dieses Frameworks auskenne.Ich versuche es trotzdem.
Nachdem die ersten beiden Plattformen für die Doku v1-v4 zuerst ein github wiki, dann WordPress war und weitestgehend von mir alleine geschrieben und gepflegt wurde, wurde nach einer Möglichkeit gesucht die immer weiter wachsenden Informationen auf mehrere Schultern zu verteilen und um den Wunsch nach (beliebiger) Mehrsprachlichkeit zu unterstützen.
Bluefox hatte dann das Framework für Website und Doku kurzerhand selbst entwickelt.
Dahinter steckt eine geniale Idee.Die Doku wurde in zwei Abteilungen unterteilt. Einmal die so genannte Adapterreferenz, und einmal die Dokumentation hinter der sich der "Rest" verbirgt.
Die Idee, die hauptsächlich auf die Adapterreferenz ausgelegt war, basiert darauf, nur noch eine Stelle zu haben, an der die Information liegt. Dann gibt es auch nur noch eine Stelle, die gepflegt werden muss.
Auf diese Quelle sollte auch jeder (indirekt) zugreifen können.
Von dieser Quelle aus, soll dann die Info auf die verschiedenen Kanäle verbreitet werden: Admin (Readme), Doku, und ggf. Forum.
Außerdem sollte diese Informationen auch automatisch in verschiedene Sprachen übersetzt werden, wenn keine native Doku vorliegt. (Dazu später mehr)Was bot sich da besser an, als die Adapterdoku in den entsprechenden Adapterrepos zu pflegen?
Der Adapterentwickler sollte dann neben der Entwicklung auch seine Doku auf Vordermann bringen. Außerdem kann dann jeder dort über einen Pull Request Änderungen für die Doku vorschlagen.
Um diese Automatisierung zu ermöglichen hat die Doku eine (weitestgehend starre Struktur, da es für jede (auch noch anzulegende) Sprache dieselbe Struktur haben muss, in der nur an einer Stelle dann z,B,
/de/gegen/ru/ausgetauscht werden muss.Daher haben wir im Vorfeld bereits 2018 (???) diese Struktur weitestgehend erstellt.
An diese Struktur müssen wir uns im Moment halten.
Im Bereich der Adapterreferenz möchte ich im Moment auch gar nicht herumspielen, sondern im Bereich der allgemeinen Doku.
Ich denke da an allgemeines zu ioBroker, Tutorials und FAQ haben es am nötigsten.Jede gefüllte Seite ist eine gute Seite!
Dort ggf. neue Strukturen anzulegen sollte nicht ganz so kritisch sein (hoffe ich).
Sollten noch Fragen bestehen, oder entstanden sein. ich habe für alles ein offenes Ohr.
