Monatsrückblick Januar/Februar 2026 ist online!

[ManfredH]

Es würde schon genügen, eine Struktur für die Dokumentation vorzugeben, an die sich dann alle an einem größeren Projekt Beteiligten halten. Und eine richtige Anwender-Dokumentation anzubieten.

@Stabilostick:

Um besser zu werden hilft nur eines: Mitmachen! 30 Jahre EDV-Erfahrung dürfen nicht ungenutzt bleiben! :) `
Mag sein. Aber jeder hat so seine Verpflichtungen (bzw. Hobbys). Und für ein weiteres Engagement fehlt mir leider die Zeit (auch wenn ich für einen Dokumentations-/Koordinations-Job sicher qualifiziert wäre).

[Stabilostick]

` > Alle suchen Bestätigung im Beruf, Bestätigung durch den Partner, Bestätigung durch die Kinder, Bestätigung auf Facebook. Und wenn wir doch mal auf etwas verzichten, dann freiwillig, aus eigenem Antrieb, auf Kohlensäure im Wasser oder Zucker im Kaffee. Wir verzichten nicht, um zu entsagen, sondern, um davon zu profitieren, das ist ein Unterschied. Gut möglich, dass viele sich deshalb lieber im Netz als in der Wirklichkeit aufhalten. Weil wir dort alles zu jeder Zeit auf Knopfdruck bekommen. Wir füllen Warenkörbe, bestellen, schicken zurück, bestellen neu. Wir lernen Menschen kennen, verlieren das Interesse, klicken sie weg, lernen neue kennen, alles – scheinbar – ohne Konsequenzen. Die Logik des Netzes ist rein konsumistisch. Das Leben aber ist dialektisch organisiert: Legt man auf der einen Seite etwas in den Warenkorb hinein, fällt auf der anderen Seite etwas heraus. Ein bisschen mehr an Sicherheit ist immer ein bisschen weniger an Freiheit – und umgekehrt. Ein bisschen mehr an Gesundheit ist meistens ein bisschen weniger an Spaß – und umgekehrt.

»Es gibt keinen Gewinn ohne Verlust und keinen Verlust ohne Gewinn«, sagt die ungarische Philosophin Ágnes Heller. Mit jeder Entscheidung für etwas entscheiden wir uns gleichzeitig gegen etwas anderes. Wir müssen immer einen Preis zahlen. Wir sind immer noch zur Freiheit verurteilt. Aber vor lauter technischer Machbarkeitshysterie und digitalem Möglichkeitswahn fällt es uns immer schwerer, Entscheidungen zu treffen und die dazugehörenden Konsequenzen zu tragen. Es scheint, als wäre uns das Wissen abhandengekommen, dass Entsagung nicht nur möglich ist, sondern auch Glück bedeuten kann. `
sz-magazin.sueddeutsche.de/leben-und-gesellschaft/sonst-noch-was-80378

[Homoran]

Ich habe mir den "Rundumschlag" gar nicht vollständig durchgelesen ;-)

Aber ich werden diesen Thread endlich mal zum Anlass nehmen den aktuellen Status kundzutun.

Ich weiß, dass ich mit der Doku inzwischen gewaltig hinterherhinke.

Abgesehen von technischen und privaten Ursachen liegt das daran, dass die website komplett neu aufgebaut werden wird.

So lange wird an der "alten" Doku nur noch das notwendigste verändert.

Spätestens mit Freigabe des Admin v3 im Stable muss ALLES neugemacht werden.

Das fängt schon mit der Erstellung neuer Screenshots, deren Beschriftung usw. an.

Es sind allerdings noch lange nicht alle Adapter an Admin v3 angepasst.

Die Doku dann noch zwei oder dreimal anfassen wird ein Ding der Unmöglichkeit - Das Thema Zeit war irgendwo schon erwähnt ;-)

Sei versichert, uns ist bekannt, dass der jetzige Zustand verbesserungsbedürftig ist, und wir dran sind.

Gruß

Rainer

PS mit dem SQL-Adapter hast du allerdings einen ganz schweren Brocken erwischt. Es wird leider auch erwartet, dass in der ioBroker Doku auch SQL und dessen Administrierung beschrieben wird, was IMHO nicht Aufgabe der ioBroker Website sein sollte, aber leider auch mein Anspruch wäre :(

[Stabilostick]

SQL for Dummies…

https://datubaze.files.wordpress.com/20 ... s_2003.pdf

Haste in 21 Tagen drauf. [emoji48]

[Jey Cee]

Ich bin ja für Tooltips Systemweit, das erspart viel Doku und und lässt sich Multilingual einbauen. Davon abgesehen taucht es dort auf woan es braucht.

Ich wollteTooltips in meinen Adaptern verwenden, aber da waren noch keine Implementiert. Soweit ich das ergründen konnte, lag das an der verwendeten Version von materializecss. Kann sein das es Mittlerweile möglich ist.

Gesendet von meinem m8 mit Tapatalk

[ManfredH]

@Homoran:

PS mit dem SQL-Adapter hast du allerdings einen ganz schweren Brocken erwischt. Es wird leider auch erwartet, dass in der ioBroker Doku auch SQL und dessen Administrierung beschrieben wird, was IMHO nicht Aufgabe der ioBroker Website sein sollte, aber leider auch mein Anspruch wäre :( `
Danke erstmal für die Erläuterung und das Feedback! Was ich damit vor allem ausdrücken wollte ist daß eine SW immer nur so gut sein kann wie die Doku ist. Mit falscher/unvollständiger Doku kommen zwangsläufig (neben Frust beim Anwender) viele Fragen im Forum, die dann genau die wieder beantworten dürfen/müssen, die die Zeit dafür besser in die Verbesserung der Doku verwenden würden. Ich hab in meiner alten 4ma zuletzt mehrere Jahre lang den Support für ein Tool gemacht, ehe ich dann beschlossen habe, den ganzen Mißverständnissen, unverständlichen Beschreibungen usw., vor allem aber den häufigen Fragen ein Ende zu machen und die Doku, die ursprünglich vom Entwickler erstellt wurde, vollkommen neu zu schreiben. Denn wenn ich eins kann dann ist das, als Mittler zwischen Entwicklern und Anwendern Dokus zu schreiben. Weil ich einerseits Anwender bin, aber auch genügend Background von der Entwicklung her habe. Mit der neuen Doku sind die Fragen deutlich zurückgegangen und konnten von mir meist mit einem Verweis auf die genaue Stelle in der Doku beantwortet werden ("RTFM" ;) ). Und wenn ich festgestellt habe, daß etwas gefehlt hat dann hab ich das umgehend ergänzt. Aber gut, das war mein Job und ich wurde dafür auch bezahlt :/

Was den SQL-Adapter angeht so erwarte ich neben der vorhandenen technischen Beschreibung (die ich bzgl. Datenstruktur usw. auch für ausreichend halte), vor allem eine verständliche Oberfläche. Und woran es da krankt hab ich ja geschreiben. Das sind definitiv nur ein paar wenige Handgriffe (Strings ändern), um die größten Unklarheiten zu beseitigen! Man kann Oberflächen durch die richtige Wortwahl durchaus weitgehend selbsterklärend machen. Nicht für jeden, aber wenn selbst ich mit vielen Jahren EDV-Background scheitere (in denen ich sehr viele Programme gesehen und installiert habe!), dann sollte das zu denken geben.

Beim ioBroker und den ganzen Adaptern, die ja von verschiedenen Entwicklung zugesteuert werden, ist m.E. eine vorgegebene Struktur für die Dokumentation, an die sich alle halten sollten, zwingend erforderlich! So wie das im Augenblick für mich nach ein paar Wochen Beschäftigung mit dem ioBroker aussieht ist das ein absoluter Wildwuchs - da macht jeder was anderes (nicht selten auch derselbe an verschiedenen Stellen). Und an der Stelle bin ich evlt. auch bereit, mich wie von Stabilostick "gefordert" mit meinem Knowhow einzubringen. Vor allem weil ich der Prototyp des Anwenders bin, der von Linux wenig Ahnung hat ;)

[Stabilostick]

Da sind wir auf der selben Wellenlänge. Vor 8 Wochen habe ich auch noch nichts vom ioBroker gewusst.

Ich bin der Auffassung, das es einen Stype-Guide für Entwickler geben muss. Z.B für den Design des User-Interfaces.

Vgl. viewtopic.php?f=20&t=15403

Das ist etwas mehr als ein technisches Template für die Erstellung eines Adapters. Adapter sollten, wenn sie eine gewisse Reife erreicht haben, in einer zentralen offiziellen Dokumentation aufgenommen werden. Diese Dokumentation muss wiederum dem Style-Guide entsprechen. Sie muss gepflegt werden, damit z.B. neue Erkenntnisse aus dem Forum dort einfließen. Vernünftige Vorgehensweisen und Paramterbeschreibung auch für Anfänger sind ein Muss. Soll die Doku in Wiki-Form sein, damit viele daran arbeiten können? Muttersprachler für Übersetzungen wären toll. Admin-UI: Tooltipps sind eine Methode. Dynamische Links für Eingabenfelder auf die Doku mit genauer Paramterbeschreibung eine weitere (und im Zweifel aktueller, da unabhängig vom Adapter updatebar).

Dann bleibt noch offen, wie mit Adaptern umgegangen werden soll, deren Entwickler sich aus der Entwicklung zurückgezogen haben oder denen das UI einfach egal ist? Was ist, wenn da eine UI-Text immer wieder zu Missverständnissen führt? Reicht da eine Dokumentation?

Ich halte den stark dezentralisierten Ansatz zur Adaptererstellung für einen der größten Stärken des ioBrokers. Neue Adapter mit tollen Funktionen erwachsen daraus. Aber er kann auch zur jetzigen Situation führen, wo im Zweifel viel zu wenig, zersplittert oder für den Endanwender unverständlich dokumentiert ist. Es steckt eben keine Firma mit entsprechenden Ressourcen dahinter.

[apollon77]

Hi ManfredH,

wie Du sicher bei den anderen Antworten zwischen den Zeilen lesen kannst ist das Thema Doku ein "Wunder Punkt".

Ideen es zu lösen gibt es, die Ressourcen und zeit sind ein anderes Thema. Und die Mehrsprachigkeit der bisherigen Ansätze (Deutsch,Englisch, Russisch, Admin noch X weitere europäische Sprachen) erledigt Ihr übriges.

Der grobe Plan ist schon länger das Adapter Ihre Doku mitbringen. Im April haben wir dazu in Kassel beim Treffen grob besprochen wie es laufen soll. Das muss man jetzt angehen, deswegen sag ich mal noch nicht so viel über die Details.

Weitere Themen sind Entwickler dazu zu ermutigen End-Nutzer-freundliche Doku zu schreiben, am Ende darf Doku die Weiterentwicklung nicht aufhalten und und und.

Alles in allem ein sehr spannendes Themenfeld, wo wir auf die Unterstützung der Community zählen werden. jeder auch noch so kleine Beitrag (sei es ein FAQ-Beitrag(Eintrag oder korrekturen an Doku) wird in Zukunft möglich und nötig sein. Das Thema ist nur zusammen zu stämmen!

Ingo

[ManfredH]

@apollon77:

Und die Mehrsprachigkeit der bisherigen Ansätze (Deutsch,Englisch, Russisch, Admin noch X weitere europäische Sprachen) erledigt Ihr übriges. ` Kenn ich - hab schon vor über 30 Jahren Software internationisiert ;)

> jeder auch noch so kleine Beitrag (sei es ein FAQ-Beitrag(Eintrag oder korrekturen an Doku) wird in Zukunft möglich und nötig sein.
Auch diese "kleinen Beiträge" stehen und fallen mit der Umsetzung. Wenn ich als Anweder/Kontributor den Eindruck habe daß meine Vorschläge im Sande verlaufen, weil der Zuständige dafür entweder keine Zeit hat (haben will) und weil's ihm sonstwo vorbeigeht, dann werd ich mir Vorschläge ganz schnell sparen. Eine Community lebt dann, wenn nicht nur viele diskutieren, sondern wenn auch was passiert. Kann ich als langjähriger Admin eines Forums nur betonen.

[apollon77]

Als gaaanz kurzer Abriss:

Ja Github ist der Platz zum Entwickeln. Er ist aber auch der Platz wo alles zu den Adaptern liegt (code und Bilder und so).

Die ganz grobe Idee ist:

Jeder Adapter hat seine Doku im Verzeichnis "docs" in seinem Github. Idealerweise eine allgemeinverständliche End-Nutzer-gerichtete Seite und gern FAQs, oder auch Expertenseiten. Auf jeden Fall aber schon hier eine Trennung zwischen Zielgruppen.

Das ganze als MD Dokumente und alle Bilder auch dort und so. SO kann jeder User hier auf Github editieren und Pull-Requests einreichen.

Weiterhin gibt es ein "iobroker.docs" Projekt wo die "Nicht adapter-spezifische" Doku drin gleicher Forum drin ist.

Das alles wird dann genommen und daraus zusammen "der Doku-Teil der Webseite" gebaut einmal am Tag oder so.

Details stimmen wir gerade ab. Also stay tuned

[ManfredH]

@apollon77:

SO kann jeder User hier auf Github editieren und Pull-Requests einreichen. `
Was dann wieder voraussetzt, daß man sich auf github a) registriert und - vor allem - b) mit der Mimik dort auch auseinandersetzt. Dafür sollte es dann zumindest auch eine Anleitung geben.

[AlCalzone]

@apollon77:

Jeder Adapter hat seine Doku im Verzeichnis "docs" in seinem Github. Idealerweise eine allgemeinverständliche End-Nutzer-gerichtete Seite und gern FAQs, oder auch Expertenseiten. Auf jeden Fall aber schon hier eine Trennung zwischen Zielgruppen.

Das ganze als MD Dokumente und alle Bilder auch dort und so. SO kann jeder User hier auf Github editieren und Pull-Requests einreichen. `

Zur Ergänzung: GitHub bietet an, aus dem docs-Ordner (oder anderen, wenn konfiguriert), automatisch eine gehostete Seite zu erstellen (Github pages).

https://guides.github.com/features/pages/

So kann das Hosting der Anleitungen direkt auf Github erfolgen. Der User schaut nur an, der Entwickler kann bearbeiten und PRs erstellen.

Wunschtraum: Vielleicht sogar ein ioBroker-flavored Template hierfür?

[Homoran]

Jedes Ding hat aber mindestens zwei Seiten ;-)

Ich habe immer angeboten, dass ich jede Doku auch in unformatiertem text (z.B. per PN) annehme und in die Doku einbaue.

Trotz mehrfachem Aufruf ist da nur gaaaanz wenig gekommen.

Leider hat sich herausgestellt, dass solche Gastbeiträge, die ich z.B. mangels Hardware nicht testen konnte irgendwannim Forum zerrissen wurde, dass dies vorn und hinten nicht passt und nichts funktioniert - Watt Nu?

Zu guter Letzt muss ich weiterhin zugeben, dass wir mit der Idee die Website/Doku umzugestalten schon sehr lange schwanger gehen, und es immer wieder an anderen Dingen hängt.

Leider haben wir uns damals (aus verschiedenen Gründen) entschieden an der bestehenden Doku nichts mehr zu ändern, in dem Glauben, dass die neue wesentlich schneller online sei. :(

@AlCalzone:

Github pages) `
Das ist/war eine der Optionen

Gruß

Rainer

[ManfredH]

@Homoran:

Leider hat sich herausgestellt, dass solche Gastbeiträge, die ich z.B. mangels Hardware nicht testen konnte irgendwannim Forum zerrissen wurde, dass dies vorn und hinten nicht passt und nichts funktioniert - Watt Nu? `
Geht's nur um die Doku? Oder auch das UI?

Meine Meinung: Es ist zwar ehrenwert, wenn jemand einen Adapter schreibt (meist weil er ihn selbst braucht). Die Frage ist dann, ob man diesen Adapter dann der Allgemeinheit "zum Fraß vorwirf". Da geht's nämlich los mit der Qualitätskontrolle. Entweder man ist drauf aus, möglichst viele Adapter anzubieten (Quantität), weil man glaubt, daß eine möglichst breite Basis dem ioBroker hilft, oder man schaut auf die Qualität und lehnt Adapter, die bzgl. UI und Doku den (natürich) gesetzten Standards nicht entsprichen, ab; ob ein Adapter in die Liste aufgenommen wird obliegt ja den Administratoren. Natürlich kann jeder sein Werk auf github veröffentlichen (und auch bewerben), aber das ist dann schon alles. Wenn der Entwickler zeigt, daß er sich um sein Werk kümmert, im Forum antwortet und die gemeldeten Bugs anpaßt, dann kann man den dann ja irgendwann in die offizielle Liste wieder aufnehmen.

> Zu guter Letzt muss ich weiterhin zugeben, dass wir mit der Idee die Website/Doku umzugestalten schon sehr lange schwanger gehen, und es immer wieder an anderen Dingen hängt. Also ich für meinen Teil finde die Seite eigentlich übersichtlich (und gut) genug. Leider halt unvollständig und teilw. veraltet.

> Leider haben wir uns damals (aus verschiedenen Gründen) entschieden an der bestehenden Doku nichts mehr zu ändern, in dem Glauben, dass die neue wesentlich schneller online sei. :(

Und in der Zwischenzeit hängen potentielle Anwender in der Luft (so wie ich). Ich kenn die Hintergründe der diversen Aktionen (z.B. Admin 3) zwar nicht, aber man muß sich halt überlegen, was irgendwelche tollen Sachen auf der einen Seite bringen, wenn auf der anderen die Anwender frustriert sind und dem ioBroker den Rücken kehren (sprich mit den Füßen abstimmen) - da ist auch nix gewonnen. Aber wie ich sehe, bestätigt sich meine langjährige Erfahrung, daß die Doku selten wirklich wichtig genommen wird und Vorrang vor anderen Aktivitäten bekommt.

Zum Glück hab ich wenigsten rudimentär Ahnung und i.d.R. auch die Zeit, mich mit den Unzulänglichkeiten auseinanderzusetzen, auch wenn's manchmal wirklich nervt (wie der 3-malige komplette Neustart meines Projekt aufgrund der Inkompatibilität des npm).

[ManfredH]

@ManfredH:

ob ein Adapter in die Liste aufgenommen wird obliegt ja den Administratoren. `
Nachtrag: aus meiner Projektleiterzeit kenne ich das Vorgehen, eine neue Software erst einmal zu pilotieren. In dem Fall würde das bedeuten, daß ein neuer Adapter erstmal einen "Beta"-Status bekommt für einen gewissen Zeitraum. Werden die Bugs/Unzulänglichkeiten behoben, gibt's schließlich die Aufnahme in die offizielle Liste. Wenn nicht, dann bleibt der Adapter halt im Beta-Status und fliegt irgendwann ganz raus.

[Homoran]

Und da gebe ich dir vollkommen recht:
@ManfredH:

Und in der Zwischenzeit hängen potentielle Anwender in der Luft `
und das missfällt mir wahrscheinlich sogar mehr als dir, weil ich weiss wo es überall brennt.

@ManfredH:

daß die Doku selten wirklich wichtig genommen wird und Vorrang vor anderen Aktivitäten bekommt. `
Dem hingegen möchte ich so vehement widersprechen wie es nur geht.

In diesem Fall hängt es an der Basis , sozusagen an dem Behälter, in den die Doku als Inhalt gebracht werden soll.

Gruß

Rainer