Neuer ioBroker-Blog online: Monatsrückblick März/April 2026

[haus-automatisierung]

Ich frage mich gerade, wo genau ich eigentlich Dinge dokumentieren soll und was gerade der richtige Weg ist. Die Dokumentation ist ziemlich zerpflückt und an vielen Stellen verteilt.

• https://www.iobroker.net/#de/documentation ist bestimmt aktuell der offizielle Weg, oder?
• Welche Rolle spiel https://www.iobroker.net/docu/index.htm?lang=de noch? Kann die Seite nicht komplett gelöscht werden? Die Screenshots dort sind auch alle komplett veraltet. Das pflegt ja niemand mehr, richtig?
• Viele Beiträge werden hier auch im Forum erstellt und gelten als "offizieller Weg". Da steckt auch viel Arbeit und Zeit drin. Warum wird das alles nicht an einer Stelle gesammelt?

Ich weiß aktuell nicht, wo ich die Leute hinschicken soll, wenn Fragen aufkommen.

[Jey Cee]

@haus-automatisierung sagte in Wo ist der richtige Platz für Doku?:

Warum wird das alles nicht an einer Stelle gesammelt?

Ganz einfach weil es niemand macht.

@haus-automatisierung sagte in Wo ist der richtige Platz für Doku?:

Welche Rolle spiel xxx noch?

Keine, bitte diesen Link entfernen.

@haus-automatisierung sagte in Wo ist der richtige Platz für Doku?:

https://www.iobroker.net/#de/documentation ist bestimmt aktuell der offizielle Weg, oder?

JA

@haus-automatisierung sagte in Wo ist der richtige Platz für Doku?:

Ich frage mich gerade, wo genau ich eigentlich Dinge dokumentieren soll und was gerade der richtige Weg ist.

Für deine Adapter ist das die jeweilige Readme.

[haus-automatisierung]

@Jey-Cee sagte in Wo ist der richtige Platz für Doku?:

Ganz einfach weil es niemand macht.

Okay, ich unterstütze dann demnächst auch bzw. starte einen Aufruf zur Unterstützung. Damit die Doku endlich mal das gleiche Niveau wie die Software bekommt ;)

Es wäre ja super schön, wenn man auf viele allgemeine Fragen mit einfachen Deep-Links in die Doku antworten könnte.

[Homoran]

@haus-automatisierung sagte in Wo ist der richtige Platz für Doku?:

Viele Beiträge werden hier auch im Forum erstellt und gelten als "offizieller Weg". Da steckt auch viel Arbeit und Zeit drin.

Das ist auch einer der Knackpunkte warum ich mit der Doku nicht weiter komme.
Ich halte es für wichtiger in solchen Fällen direkt zu helfen, und das in dem Forum zu "DOKUmentieren", außerdem erachte ich es als extrem wichtig über das Forum das Feedback zu erhalten, wo es bei den Usern klemmt, um dies dann auch adäquat in der Doku umzusetzen.
Was nutzt eine sterile "korrekte" Doku wenn sie nicht die Probleme im realen Leben erklärt, weil sie für den Doku-Schreiber nicht existieren??

Das Ende vom Lied ist, dass für die eigentliche Doku die Zeit fehlt.

Dazu kommt natürlich auch noch, dass es bei den inzwischen 400 Adaptern so häufig zu Änderungen kommt, dass als Quintessenz

@haus-automatisierung sagte in Wo ist der richtige Platz für Doku?:

Die Screenshots dort sind auch alle komplett veraltet.

genau so etwas herauskommt, und man direkt wieder von vorne anfangen kann, bevor die letzte Version der Doku online gegangen ist.

[da_Woody]

@haus-automatisierung viele fangen schon mit WIKIs an.

[Homoran]

@da_Woody sagte in Wo ist der richtige Platz für Doku?:

viele fangen schon mit WIKIs an.

haben wir in 2014 auch ;-)

Gottseidank taucht das jetzt endlich nicht mehr bei google auf

[Thomas Braun]

Ich hab mir dazu auch Gedanken gemacht und mir zumindest jetzt mal die Docu über git für mich geforked und habe vor daraus PullRequest zu generieren.
Der Wildwuchs über drei (oder sind es sogar mehr) Quellen, die alle nüchtern betrachtet bestenfalls als Baustelle zu betrachten sind, ist mir auch zu viel.

Das ist aber zugegeben alles andere als niederschwellig, den Ansatz eines wiki würde ich eigentlich bevorzugen. Warum ist das seinerzeit wieder beerdigt worden? Oder ist das gar nicht richtig ans Leben gekommen?

[Homoran]

@Thomas-Braun sagte in Wo ist der richtige Platz für Doku?:

ist das gar nicht richtig ans Leben gekommen?

so war es.
Um eine vorhandene Plattform zu nutzen wurde das Wiki des Github-Repositories genutzt.
Aber auch da hatte ich alles alleine gemacht ;-)

Den Code konnte ich dann relativ schnell vollständig in der nächsten Version mit WordPress übernehmen.
Die jetzt noch herumgeisternden Reste sind Teile der 3. Version mit Wordpress.

Aufbauend auf der Hoffnung, dass in den Github-Repos der Adapter wenigstens die Adapterreferenz als Bestandteil der Adapter entstehen würde, sollten diese automatisiert in ein neues Format gegossen werden.
Dieses Format ist die jetzige Doku, die Referenz in den jeweiligen Adaptern aber immer noch nicht umgesetzt.
Und wie bereits in einem anderen Thread erwähnt bringt auch eine rein technische Referenz eines Entwicklers einem Anfänger herzlich wenig.
Dann muss doch noch mal alles neu erfunden werden.

Leider wird der Umfang nicht weniger, und die Zeit dafür nicht mehr :-(

[haus-automatisierung]

@Homoran sagte in Wo ist der richtige Platz für Doku?:

genau so etwas herauskommt, und man direkt wieder von vorne anfangen kann, bevor die letzte Version der Doku online gegangen ist.

Naja, die Frage ist ja auch, WAS man dort dokumentiert. Also wo zieht man die Grenze. Meiner Meinung nach sollte dort nur das Grundkonzept dokumentiert werden. Also alles, was Entwicklung, generelles Handling von Nachrichten, Datentypen usw. entspricht. JS-Controller halt.

Alles was darüber hinaus geht, z.B. der Admin, ist ja wieder ein eigener Adapter. Jetzt könnte man darüber streiten, ob der Admin-Adapter überhaupt in die Doku dort gehört - da mir ja oben gesagt wurde, dass Adapter-Spezifisches auch direkt in der README im Repo dokumentiert werden sollte (was auch den Vorteil hätte, dass es immer zur Version passt).

Nur sind viele Konzepte ja auch schwer zu erklären, wenn man nicht den Admin als Referenz dafür nimmt. Man dreht sich etwas im Kreis meiner Meinung nach. Genauso VIS und Widgets, vis APP, IoT, Cloud, ...

Schwierig - daher ja auch die Ausgangsfrage :)

[Homoran]

@haus-automatisierung sagte in Wo ist der richtige Platz für Doku?:

WAS man dort dokumentiert. Also wo zieht man die Grenze.

im Prinzip sollte IMHO alles dokumentiert werden so dass ein Anfänger alles bedienen kann und ein paar Hintergrundinformationen bekommt.

Die ReadMe in den Adaptern sind bis auf wenige sehr gute Ausnahmen nicht dafür geeignet

@haus-automatisierung sagte in Wo ist der richtige Platz für Doku?:

Also alles, was Entwicklung, generelles Handling von Nachrichten, Datentypen usw. entspricht. JS-Controller halt.

Das hat IMHO in einem speziellen Entwickler-Teil seinen Platz ist für einen Einsteiger definitiv nicht hilfreich und führt genau zu dem Ergebnis, das leider schon viel zu weit verbreitet ist: 'ioBroker ist nur was für Nerds'