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

[kmxak]

Wenn ihr Hilfe benötigt schreibt doch eine Liste ins Forum.

Ich könnte die Anleitungen/Doku… Anfänger technisch Analysieren und bei Verständnisproblemen Rückmeldung geben.

Infos zusammentragen. / Lösungen aus dem Forum Dokumentieren oder so.

Wiki ist manchman schon praktisch.

[thobastian]

Hallo Zusammen,

also ich glaube, hier könnte echt was Interessantes entstehen.

Um mal zu verdeutlichen, was ich meine, hier mal eine Idee, wie wir eine gute Dokumentation eines Adapters bekommen.

Grundgerüst könnte z.B. Adapter "history" sein. So sieht die Imhaltspunkte aus:

• Steckbrief (Version,Voraussetzungen,Entwickler,Stichworte,Guthub,Plattform,License)

• Konfiguration (div.Einstellungen)

• Bedienung (Anleitungen, Videos usw)

weitere mögliche Punkte:

• Beispiele

So gut dokumentiert, wie der Adapter History sind leider die wenigsten Adapter. z.B. der YAHA (Yet another Homekit adapter). Das hat seine Gründe.

Der Homekit Adapter hat bei mir nicht funktioniert und ich suchte nach Alternativen. Dabei fand ich YAHA. hier das Froum:

http://forum.iobroker.net/viewtopic.php?f=23&t=4136.

Dort konnte mir u.a. Dutchman helfen.

Aber für mich ist es nun nach der Lösung meines Problems wichtig, die Erkenntnisse zu sichern. Dutchman hat sogar ein Erklär-Video gedreht! :idea:

Das finde ich wirklich schade, wenn da im Forum "vergammelt". Sorry, aber das wird es, wenn die schönen Beispiele von Dutchman UND das Video nicht in die Beschreibung gesichert werden.

Es ist als Anfänger sehr schwierig im Forum zu suchen. Das gilt für alle Foren. Nicht nur hier.

Die Dokumentation muss ja kein Wiki sein, aber beim Wiki gefällt mir, dass jeder die Doku erweitern kann.

Natürlich ist der Grad der Pflege immer abhängig von Personen, Sichtweisen usw. Das kann man sowieso nicht ausmerzen. Es gibt ja keine Doku-Pflicht. (zum Glück!).

Aber wenn hier die Doku immer weiter aufgebohrt wird & aktuell gehalten wird, sind wir ein gutes Stück weiter.

Vorteile:

• Verweis in den Foren auf wiederkehrende Fragen per Link

• viel mehr zufriedene User (Auch User, die keine Entwickler sind, wie ich)

• in der Entwicklung befindene Adapter werden öffentlicher

etc..

nächste Schritte wären:

• Festlegen, welche Oberpunkte in die Beschreibung sollen (siehe oben)

• wer macht was?

• Adaptermenü besser strukturieren (Adapter aus Startseite entfernen, Beginnertutorial für Homematic und Raspi-User schreiben)

weitere Ideen? oder was meint ihr?

Gruß

Thomas

[Homoran]

Wie ich bereits schrieb sind nur wenige Adapterdokus wirklich fertig, obwohl selbst das mit Bluefox' rasanten Entwicklungstempo fraglich ist ;-)

• Admin (mit allen seinen Reitern)

• hm-rps

• hm-rega

• vis

• flot

• History

• SQL

• influxDB

alle weiteren Dokus sind teilweise 2-3 Jahre alt, wenn überhaupt vorhanden.

Die weitere Aktualisierung ist im Moment "on hold" weil sie alle in ein neues Format übertragen werden für die neue Website, die auf dem Usertreffen in Kassel vorgestellt wurde.

(die Frage nach dem YAHKA-Adapter bitte in separatem Thread stellen!)

Gruß

Rainer

[apollon77]

Hey All,

ich habe auch nach einigen Gesprächen nochmals nachgedacht.

Im aktuellen Stand ist die GitHub README.md zum Adapter die Haupt-Doku für die meisten Adapter. Einige finden "Github zu technisch", aber das liegt nur daran wie die Entwickler (meistens) dokumentieren :-( Fakt ist: Die Github README - bzw eine vom Entwickler definierte Datei/Link - ist die Doku die im Admin beim Fragezeichen hinter dem Adapter verlinkt ist.

Weil die Doku meist sehr rudimentär ist erstellt Homoran für die wichtigen Adapter noch zusätzliche Doku auf der Webseite. Aber zu erwarten oder anzunehmen das das jemals alles umfassen wird und kann ist das eher Zusatz.

Die Idee mit der neuen Webseite ist das jeder Adapter seine Webseiten-Doku selbst enthält und zur Webseite beisteuert. Die Webseite ist also noch nicht da.

Daher hier meine Meinung wenn man als User für einen Adapter Doku beisteuern oder verbessern will:

• Kurzfristig:

• zum Github Projekt des Adapters gehen (web)

• README.md als File anklicken

• Stift Icon = Edit

• Änderungen einbauen

• Unten dann Name und kurze beshreibung der Änderung und dann "propose change" klicken

Mittelfristig wenn alle Adapter-Dokus im Adapter sind … geht das per Webseite :-)

[Jeeper.at]

Der folgende Thread ist ein klasse Beispiel warum einerseits ein Anfänger nichts findet, und warum manche Probleme nicht gelöst werden.

http://forum.iobroker.net/viewtopic.php?t=6325#p65179

Der Thread ist als gelöst gekennzeichnet, trotzdem wird ein neues Problem drangefügt.

Da er gelöst wurde, warum sollte ich als Entwickler dann noch reinschauen.

Nochmal mein Vorschlag solche Threads zu schließen und schon hat man ein Suchbereiche Nachschlagewerk

Lg

Günther

[aleks-83]

Ich frage mich immer wieder wo ich die WIKIs oder DOKUs zu den Adaptern finde.
Als Link im Adapter wird man auf die GitHub Seite geleitet.
Dort steht oft nicht viel drin.

Dann erstellt man hier im Forum einen Thread mit einer Frage und wird angepflaumt warum man denn die Adapter Doku nicht gelesen hat.
Wenn dort aber nicht viel steht, kann ich ja nicht wissen wir es funktioniert!?

Beispiel hue Adapter: Was bedeutet "natives Ein-/Ausschaltverhalten" oder "Legacy-Struktur"?

[Jey Cee]

@aleks-83 Die Böse Antwort: Das Forum ist die Dokumentation.
Hier schreiben unglaublich viele, teils wirklich super sachen. Davon könnte man locker einiges 1:1 in die Doku übernehmen, wobei die erste Anlaufstelle dann in jedem fall Github wäre. Und genau das ist das Problem, zu wenige erstellen Pull Requests mit ihren Beschreibungen.
Neben der Entwicklung bleibt halt dann auch noch die Doku an den Entwicklern hängen. Und sind wir mal ehrlich eine gute Doku zu schreiben ist mindestens genau so schwierig wie einen Adapter zu Entwickeln.
Aus Entwickler sicht gibt es dazu noch ein Problem, man selbst versteht ja wie man einen Adapter benutzen muss und sieht vieles auch gar nicht.

[BBTown]

@aleks-83 sagte in Dokumentation / WIKI - Diskussion:

Beispiel hue Adapter: Was bedeutet "natives Ein-/Ausschaltverhalten" oder "Legacy-Struktur"?

hier hast Du gerade zwei Funktionen bzw. Einstellungen erwischt, die brandneu sind und daher ggf. noch nicht in ein DOKU oder auf GitHub eingeflossen sind.

Natives Ein-/Ausschalten siehe hier

Legacy-Struktur: der HUE-Adapter in der v2.x.x legt die Datenpunkte etwas anders an, als die v1.x.x. Setzt man diesen Haken, dann wird die ursprüngliche Struktur (sofern jemand bereits die v1.x.x im Einsatz hatte) nicht angetastet bzw. bleibt erhalten.

[foxriver76]

@aleks-83 Steht doch alles hier anpflaum

Wenn man empfindet, dass nötige Dokumentation in der Readme fehlt, darf man auch gerne ein Issue erstellen um mich darauf aufmerksam zu machen. Denke die meisten Entwickler haben da nichts gegen. ;-)

[aleks-83]

Hey, Danke für eure Rückmeldungen.

Versteht mich nicht falsch...
Ich wollte niemande direkt ansprechen oder an den Pranger stellen sondern allgemein auf die Adapter Dokumentationen aufmerksam machen.

Ich kann mir auch vorstellen dass das Erstellen und Pflegen eines Adapters schon viel Zeit erfordert und dass dann die Zeit für eine Doku fehlt. Den Aufwand weiß ich auch auf jeden Fall zu schätzen. Habe großen Respekt davor.

@foxriver76 sagte in Dokumentation / WIKI - Diskussion:

@aleks-83 Steht doch alles hier

Seit wann denn das?
Ich war vorhin noch auf der Seite, da stand es noch nicht.
Oder war ich auf einer alten Seite?
Dort stand oben dick "moved to ... (internet Link zu GitHub)
Wenn man drauf geklickt hat, kam man wieder auf die gleiche Seite.

[foxriver76]

@aleks-83 sagte in Dokumentation / WIKI - Diskussion:

Seit wann denn das?
Ich war vorhin noch auf der Seite, da stand es noch nicht.
Oder war ich auf einer alten Seite?
Dort stand oben dick "moved to ... (internet Link zu GitHub)
Wenn man drauf geklickt hat, kam man wieder auf die gleiche Seite.

Habe es aufgrund deines Hinweises eingepflegt.

[aleks-83]

Vielen Dank.

Schnell und informativ !

[Jey Cee]

@aleks-83 sagte in Dokumentation / WIKI - Diskussion:

Ich wollte niemande direkt ansprechen oder an den Pranger stellen sondern allgemein auf die Adapter Dokumentationen aufmerksam machen.

Damit hat niemand ein Problem, es ist nur so das es schon häufig bemängelt wurde. Darauf hin hat man versucht Leute zu finden die bereit sind bei der Doku zu helfen, aber die Beteiligung war immer gering oder nur von kurzer Dauer. Technisch gab es auch versuche das zu Vereinfachen, aber es bleibt Trotzdem Aufwand.

Aber wie du siehst hilft es auch manchmal schon wenn man dem Entwickler die Richtigen infos an die Hand gibt. Auch das ist eine Hilfe.

[aleks-83]

OK super.

Wenn ich helfen kann freue ich mich auch.
Ich bekomme so viel aus diesem Forum und von den ioBroker Entwicklern

Ich hatte auch schon in einem anderen Thread versucht Verbesserungsvorschläge zu machen.
Auch hier wurde man auf GitHub verwiesen, wo ich dann auch Issues erstellt habe.

Aber irgendwie muss man das ganze doch übersichtlicher und einfacher gestalten können mitzuwirken!?
Ohne dass sich die Entwickler angegriffen, überrumpelt oder überfordert fühlen!?