Jahresrückblick 2025 – unser neuer Blogbeitrag ist online! ✨

[RoddiEF]

Die Doku sollte m.M nach so einfach wie möglich sein und die Grundlagen (evt. mir einfachen Beispielen) behandeln.
Fachausdrücke, die nur Raketenwissenschaftler verstehen, sollten am Ende vorkommen.

[hydrotec]

@homoran

Die Frage ist halt, wie wir die Dokumentation aufbauen sollen.
MQTT allgemein, und alle in Beziehung stehende Adapter mit einbinden.
Oder für jeden Adapter eine eigene Dokumentation.

[Homoran]

@hydrotec sagte in MQTT Broker/Client Adapter:

wie wir die Dokumentation aufbauen sollen.

ich fürchte ja, dass du bereits in der Adapterref unterwegs bist.
Da gibt es kein allgemein, nur Adapterspezifische Anleitungen.

Ich hatte damals immer eine (mehr oder weniger) kurze Einleitung zu dem Hintergrund der Technik o.ä. gemacht.
Allerdings ist das MQTT wieder speziell, weil es da den Client/Broker und den Client Adapter gibt.

Ich denke dass dann die Hintergrundinfo wohl besser beim Client/Broker untergebracht is

[derAlff]

@RoddiEF oder einfach nur unterteilen in Grundlagen und Fortgeschrittene.

Ich bin jedenfalls bei dir. Die Grundlagen sollten so beschrieben sein, dass mein 7-Jähriger Sohn das rafft ☺️.
Ich schaue Mal, ob ich meine Notizen noch habe.

[hydrotec]

@roddief

Es ist nicht leicht, eine, für beide Seiten (Einsteiger/Raketenwissenschaftler) verständliche Doku zu erstellen.
Ich versuche mein Bestes, damit der Einsteiger sich relativ schnell mit der MQTT Welt auseinander setzen kann.
Ebenso muss ich aber auch vertiefte Einblicke geben, damit ein "Profi" einen Sinn in dieser Doku sieht.
Werde mir noch Gedanken machen, wie das umzusetzen ist.

Gruß, Karsten

[Homoran]

@deralff sagte in MQTT Broker/Client Adapter:

oder einfach nur unterteilen in Grundlagen und Fortgeschrittene.

@crunchip hat mir dort: https://forum.iobroker.net/topic/51619/formatierungshilfe-gesucht/6?_=1643051054226 ein Snippet zur Verfügung gestellt, dass den Fortgeschrittenen Teil verstecken könnte.
Hab es aber noch nirgendwo eingebaut - wäre aber von meiner Seite die sauberste Lösung um den Lesefluss für Einsteiger zu erhalten, und interessierte klappen dann weiter auf

[RoddiEF]

@hydrotec
Das es nicht Einfach wird beide Seiten zufrieden zustellen ist mir klar.
Was aber wichtig ist (m.M.) , das die Anleitung in Deutsch ist.
Englische Sachen findet man vieles im Internet (wenn man Sucht), aber in Deutsch und vor allem Verständlich, wird es schwierig.

[hydrotec]

@homoran

Ich denke, da sollten wir uns einmal, in einer ruhigen Minute dazu unterhalten.
So ganz verstehe ich es noch nicht, warum die Struktur der Doku,
wenn sie einmal erstellt ist, sich nicht mehr abändern lässt.
Wie gesagt, ich hätte noch die ein oder andere Frage generell,
vermulich wird es das Beste sein, wir unterhalten uns über Teams, oder Ähnlichem.

[derAlff]

@homoran das ist ne Idee!
Ich als Nicht-Web-GUI-Talentierter.... Da kann man bestimmt auch nen Button hin machen, der alles aufklappen, oder?

[Homoran]

@hydrotec sagte in MQTT Broker/Client Adapter:

So ganz verstehe ich es noch nicht, warum die Struktur der Doku,
wenn sie einmal erstellt ist, sich nicht mehr abändern lässt.

das hier hast du aber gelesen?
https://forum.iobroker.net/topic/51731/grundlagen-der-struktur-für-die-doku

[hydrotec]

@roddief

Ich erstelle die Doku in Deutsch.
Doch wir dürfen fremdsprachige Einsteiger nicht aussen vor lassen.
Wir wollen doch eine große Familie werden, oder ;-)

[Homoran]

@deralff sagte in MQTT Broker/Client Adapter:

das ist ne Idee!

die habe ich schon seit der zweiten Doku, aber nicht das Wissen sie umzusetzen.

[mickym]

@hydrotec Ehrlich gesagt finde ich gerade diesen Adapter im jetzigen Umfeld beschreiben zu wollen als problematisch, da er nicht dem Regelwerk der Hierarchies folgt und auch selbstständig keine Objekte anlegt. Aber ich will das hier nicht noch mal diskutieren. Die Frage ist halt nur ob es Sinn macht etwas zu dokumentieren, was sich eben zur Zeit nicht mit mqtt verträgt.

Ich habe hier die derzeitige Problematik ja nochmals erklärt:
https://forum.iobroker.net/topic/50721/core-entwicklung-zu-schnell/53?_=1642957059965

Für Shellies jedenfalls mit der Version 1 - wird es jedenfalls Probleme geben. Man kann zwar das wieder extern lösen, aber die prinzipielle Problemtik ist in meinen Augen nicht gelöst.

[Homoran]

@mickym sagte in MQTT Broker/Client Adapter:

Aber ich will das hier nicht noch mal diskutieren.

es geht ja nicht um die Dinge, die du da monierst, sondern um das Prinzip vom MQTT und die Bedienung des Adapters

[mickym]

@homoran sagte in MQTT Broker/Client Adapter:

@mickym sagte in MQTT Broker/Client Adapter:

Aber ich will das hier nicht noch mal diskutieren.

es geht ja nicht um die Dinge, die du da monierst, sondern um das Prinzip vom MQTT und die Bedienung des Adapters

Nun zur Bedienung eines MQTT Adapters gehört es über eigens angelegte Datenpunkt - topics zu publishen und das geht halt nicht in jedem Fall. Das gehört doch zur Bedienung des Adapters und ist eine grundlegende Eigenschaft über eigens angelegte Datenpunkte mqtt topics zu publishen.

[RoddiEF]

@hydrotec said in MQTT Broker/Client Adapter:

Doch wir dürfen fremdsprachige Einsteiger nicht aussen vor lassen.

Das mag ja sein und war nicht mein Ansinnen , aber die meisten Adapter und Dokus dazu sind ja auf Englisch. :(
Ich habe viele Stunden mit DeepL verbracht, da mein Schulenglisch (ist fast 40jahre her) mich nicht weitergebracht haben und sich mir dadurch der Sinn nicht erschlossen hat.

[hydrotec]

@homoran sagte in MQTT Broker/Client Adapter:

das hier hast du aber gelesen?

Noch nicht, werde es nachholen.
Zur Zeit ensteht gerade zum Thema Doku viel Neues, das muss ich erst einmal unter einen Hut bringen ;-)

[Homoran]

@hydrotec sagte in MQTT Broker/Client Adapter:

Noch nicht, werde es nachholen.

mach das.
Hier ein Ausschnitt des Menüs aus dem Bereich Tutorials:

    "Tutorials": {
      "title": {
        "en": "Tutorials",
        "de": "Tutorials",
        "ru": "Уроки",
        "zh-cn": "教程文档"
      },
      "pages": {
        "Introduction": {
          "title": {
            "en": "Introduction",
            "de": "Tutorial",
            "ru": "Руководство",
            "zh-cn": "教程"
          },
          "content": "tutorial/README.md"
        },
        "First setup": {
          "title": {
            "en": "First setup",
            "de": "Tutorial",
            "ru": "учебник",
            "zh-cn": "教程"
          },
          "content": "tutorial/setup.md"
        },
        "User interface": {
          "title": {
            "en": "User interface",
            "de": "Tutorial",
            "ru": "учебник",
            "zh-cn": "教程"
          },
          "content": "tutorial/admin.md"
        },
        "Manage adapters": {
          "title": {
            "en": "Manage adapters",
            "de": "Adapter verwalten",
            "ru": "Управление адаптерами",
            "zh-cn": "管理适配器"
          },
          "content": "tutorial/adapter.md"
        },
        "Simple logic": {
          "title": {
            "en": "Simple logic",
            "de": "Tutorial",
            "ru": "учебник",
            "zh-cn": "教程"
          },
          "content": "tutorial/logic.md"
        },
        "Visualisation": {
          "title": {
            "en": "Visualisation",
            "de": "Tutorial",
            "ru": "учебник",
            "zh-cn": "教程"
          },
          "content": "tutorial/viz.md"
        },
        "Data logging": {
          "title": {
            "en": "Data logging",
            "de": "Tutorial",
            "ru": "учебник",
            "zh-cn": "教程"
          },
          "content": "tutorial/history.md"
        },
        "Charts": {
          "title": {
            "en": "Charts",
            "de": "Tutorial",
            "ru": "учебник",
            "zh-cn": "教程"
          },
          "content": "tutorial/flot.md"
        },

Hier siehst du auch, dass in de noch über all nur Tutorial steh. Habe ich zwar geändert gehabt, wurde aber durch einen pullrequest wieder überschriebn :-(
Die Pfade sind alle gleich, der Teil davor ist die Sprach-Hierarcheiebene, davor wieder der restliche Pfad.
Das muss bei der automatischen Übersetzung so bleiben

[hydrotec]

@mickym

Schau ich mir noch an, wie man das am Besten regeln könnte.
Generell ist es ja möglich, wenn auch umständlich, die von dir geforderten Datenpunkte zu erstellen.

Bitte verstehe uns auch.
Wenn wir mit einer Dokumentation warten, bis ein Programm fehlerfrei funktioniert,
dann wird es allgemein recht wenig Dokus geben.
Das soll kein Vorwurf an die Entwickler sein, ein Programm, welches Fehlerfrei funktioniert,
gibt es in meinen Augen nicht. (Es gibt doch immer was zu wurschtln ;-) )

[Homoran]

@hydrotec sagte in MQTT Broker/Client Adapter:

Bitte verstehe uns auch.
Wenn wir mit einer Dokumentation warten, bis ein Programm fehlerfrei funktioniert,
dann wird es allgemein recht wenig Dokus geben.

deswegen wollen wir im Moment nicht im Bereich der Adapterref arbeiten!
Die läuft weitestgehend. Da muss an der Wurzel angepackt werden. an der Doku in dem Adapterrepo.
Von da aus geht es dann automatisch