UPDATE 31.10.: Amazon Alexa - ioBroker Skill läuft aus ?

[hydrotec]

Jetzt habe ich den Absatz "Protokoll" in der Doku zu MQTT angepasst, wie ich ihn stehen lassen würde.

Ich bitte euch um Unterstützung, und den Absatz einmal gegenzulesen,
mit der Bitte um Rückmeldung, wie ihr das seht.
Ist zuviel, oder zuwenig Inhalt vorhanden?
Sind mir generelle Fehler unterlaufen?

Gruß, Karsten

[Asgothian]

@hydrotec

Vorweg - Gute Arbeit. Bitte die folgenden Punkte als Anregungen verstehen.

Dinge die mir aufgefallen sind:

1. Im Diagramm ist ein Konstrukt aus 2 Brokern , 3 Geräten und einem Client gezeigt. Im Text wird von "dem Broker" gesprochen - implizit darf es also nur einen geben. So kenne ich das bisher auch. Ein Broker, beliebig viele Clients. (vielleicht ist meine Information da aber falsch)
2. Der Text ist an vielen Stellen schwer zu lesen. Beispiel(e) sind zur besseren Lesbarkeit dieses Postes in Spoilern:

• Es fehlen strukturierende Elemente oder sie sind nicht durch Formatierung hervorgehoben.
• Einzelne Sätze lesen sich wie Antworten auf (im Text nicht gestellte) Fragen.
• Es scheint jeder Satz ein eigener Absatz zu sein - manchmal sogar nur ein Teil eines Satzes
  
  Spoiler

  
  Was steckt hinter den Begriffen Topic, Payload und abonnieren.
  Unter Topic kann man sich eine Art Verzeichnisstruktur vorstellen.
  Diese Struktur wird meistens von den Herstellern vorgegeben,
  kann jedoch ebenso von Anwendern definiert werden.
  Kommt darauf an, um was für eine Art von Gerät es sich handelt.
  Grundsätzlich wird in einer Pfadangabe definiert, unter welcher Rubrik,
  von welchem Gerät und in welcher Sparte sich die Information (Payload) befindet.
  
• Die Formatierung von Beispielen als Multiline Code unterbricht den Lesefluss. In Kombination mit der fehlenden Hervorhebung von strukturierenden Elementen macht es den Text schwer verständlich. ggf. ist eine Formatierung als single line code an dieser Stelle besser.

Spoiler

Die zwei gängigsten Wildcards sind # und +.
Angenommen, das Topic ist folgendermaßen aufgebaut.

myhome/client/sensors/temperature

Dann kann man anschließend die angeforderten Topics mit den Wildcards anpassen.

Hier werden alle Attribute,
welche unter "myhome/client/sensors" gesendet werden, empfangen.

myhome/client/sensors/#

Hier werden alle Sparten (inkl. aller Attribute),
welche unter "myhome/client" gesendet werden, empfangen.

A.

[Homoran]

@asgothian sagte in [Doku] Themensammlung zu MQTT allgemein:

So kenne ich das bisher auch. Ein Broker, beliebig viele Clients. (vielleicht ist meine Information da aber falsch)

So kenne ich das auch, aber es soll auch Konstrukte mit mehreren Brokern geben.

[hydrotec]

@asgothian sagte in [Doku] Themensammlung zu MQTT allgemein:

@hydrotec

Vorweg - Gute Arbeit.

Dankeschön :-)

Bitte die folgenden Punkte als Anregungen verstehen.

Selbstverständlich, da ich ja recht neu in dem Thema Doku bin, kann ich jegliche Art von Kritik,
positiv wie negativ, gebrauchen.
Im Gegenteil, ich bin dankbar zu konstruktiven Rückmeldungen.

1. Im Diagramm ist ein Konstrukt aus 2 Brokern , 3 Geräten und einem Client gezeigt. Im Text wird von "dem Broker" gesprochen - implizit darf es also nur einen geben. So kenne ich das bisher auch. Ein Broker, beliebig viele Clients. (vielleicht ist meine Information da aber falsch)

Da muss ich die beiden unterschiedlichen Konfigurationen noch besser hervorheben.

2. Der Text ist an vielen Stellen schwer zu lesen. Beispiel(e) sind zur besseren Lesbarkeit dieses Postes in Spoilern:

• Es fehlen strukturierende Elemente oder sie sind nicht durch Formatierung hervorgehoben.
• Einzelne Sätze lesen sich wie Antworten auf (im Text nicht gestellte) Fragen.
• Es scheint jeder Satz ein eigener Absatz zu sein - manchmal sogar nur ein Teil eines Satzes
• Die Formatierung von Beispielen als Multiline Code unterbricht den Lesefluss. In Kombination mit der fehlenden Hervorhebung von strukturierenden Elementen macht es den Text schwer verständlich. ggf. ist eine Formatierung als single line code an dieser Stelle besser.

Ich hatte versucht, mich weitestgehenst an die Styleguide Dokumentation zu halten.
Und so wirklich glücklich bin ich mit der jetzigen Formatierung auch nicht.
Wie ich ja schon einmal erwähnt hatte, sind das meine ersten Gehversuche zu Markdown.
Wenn es dir nichts ausmacht, und du die Zeit dafür hast, könntest du mir bitte ein Beispiel zur Verfügung stellen,
wie du das umsetzen würdest. Also nicht die ganze Seite, nur ein zwei Blöcke, für mich zur Vorlage.
Gerne direkt in der von mir erstellten Doku.
Letztendlich soll es ja allen hilfreich sein, und ich kann mich zu Markdown weiterbilden.
Vorab schon ein Dankeschön.

@homoran sagte in [Doku] Themensammlung zu MQTT allgemein:

So kenne ich das auch, aber es soll auch Konstrukte mit mehreren Brokern geben.

Konstrukte mit zwei, oder mehreren Brokern, ist schon möglich, doch das war von mir so nicht geplant.
In der Grafik wollte ich einfach nur die zwei Möglichkeiten abbilden, wie MQTT innerhalb von ioBroker genutzt werden kann.
Wie ich @Asgothian schon geantwortet hatte, muss ich das besser verdeutlichen, das hier nicht zwei Broker zur gleichen Zeit gemeint sind.
Eventuell auch zwei Grafiken verwenden?

EDIT:

@asgothian sagte in [Doku] Themensammlung zu MQTT allgemein:

Die Formatierung von Beispielen als Multiline Code unterbricht den Lesefluss. In Kombination mit der fehlenden Hervorhebung von strukturierenden Elementen macht es den Text schwer verständlich. ggf. ist eine Formatierung als single line code an dieser Stelle besser.

Hab jetzt mal auf single line code umgestellt, gefällt mir besser.
Danke noch mal zu dem Tipp :+1:

[Homoran]

@hydrotec Bin jetzt endlich mal dazu gekommen mir das auf Github anzusehen.
sieht sehr gut aus - insbesondere die Grafik.
Jetzt weiß ich auch worum es mit den zwei Brokern geht,

Vielleicht reicht es die Linie zum ersten oder/und zweiten Broker in verschiedener Punktierung/Strichelung zu machen.

Dann hast du noch etwas Platz rechts unten in der Grafik.
Ich weiß nicht ob das noch wirklich passt, aber vielleicht könnte man dort eine Legende setzen.
Nach den letzten Diskussionen im Forum, wo neue User tiefergreifende spezielle Lösungen haben wollen, stellt sich immer wieder heraus, dass diese oft des Englischen nur begrenzt mächtig sind.

• publish = veröffentlichen = senden
• subscribe = abonnieren = empfangen
• payload = Paketdaten = Werte

damit die wichtigsten Fachbegriffe direkt am Diagramm stehen

Zum Stil möchte ich noch sagen, dass es wirklich schwierig ist den style guide mit einem flüssig zu ledenden Text umzusetzen
Wieso es jedesmal zu einem Zeilenumbruch kommt ist mir schleierhaft, da MD angeblich mit einem einfachen <Return> nur im Quelltext umbricht, damit dieser leichter zu lesen ist, aber nicht auf der fertigen Seite

[hydrotec]

@homoran

Zu den Fachbegriffen, hatten wir ja schon einmal, an andere Stelle, eine Diskusion,
in der sich herauskristalisiert hat, das Fachbegriffe, die allgemein in der IT-Welt verwendet werden,
nicht vom englischen ins deutsche übesetzt werden sollten.
Deswegen, hab ich sie in der Grafik so belassen, wie sie allgemein gebräuchlich sind.
Weiter unten in der Beschreibung, sind Erläuterungen enthalten, was diese Begriffe bedeuten.
Kann das gerne mit anpassen, wenn gewünscht.
Ich muss die Grafik eh noch einmal überarbeiten, damit die zwei Konfigurationen besser kenntlich gemacht werden.

Wieso es jedesmal zu einem Zeilenumbruch kommt ...

Den hab ich, wie in dem Style Guide gefordert, nach 80 Zeichen eingefügt.
Auszug Style Guide

• Dokumente sollen einen Zeilenumbruch bei 80 Zeichen haben.

Es ist echt schwer, das umzusetzen, ohne das der Lesefluss gestört wird.
Doch es muss ja einen Hintergrund geben, das es gefordert wird, oder?

[Homoran]

@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:

hab ich sie in der Grafik so belassen, wie sie allgemein gebräuchlich sind.

ist ja korrekt, da wo sie sind sollen sie ja auch so bleiben.
Mein Vorschlag war den "freien" Platz in der Grafik für eine Legende/Glossar zu nutzen

@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:

Weiter unten in der Beschreibung, sind Erläuterungen enthalten, was diese Begriffe bedeuten.

hab ich gesehen und auch erwähnt. aber.....
ich hatte das Bild angeklickt, das geht in einem zweiten Tab/Fenster auf und da kann man den Chart viel besser sehen (was er verdient hat!). Da dacht eich nur, es wäre schön jetzt auch die drei Befgriffe noch erklärt zu haben.

@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:

Wieso es jedesmal zu einem Zeilenumbruch kommt ...

Den hab ich, wie in dem Style Guide gefordert, nach 80 Zeichen eingefügt.
Auszug Style Guide

Dokumente sollen einen Zeilenumbruch bei 80 Zeichen haben.

Es ist echt schwer, das umzusetzen, ohne das der Lesefluss gestört wird.

ich weiss. Das habe ich ja verstanden,

Der Hintergrund ist, dass im RAW Modus auch der Inhalt noch lesbar bleiben soll und nicht 280Zeichen je Zeile enthält.

Üblicherweise bedeutet bei MD ein einfacher Zeilenumbruch im RAW, dass er im endgültigen Zusatnd nicht zu sehen ist.
Dafür bedarf es einen doppelten Zeilenumbruch im RAW.
Den hast du nicht.

Das hatte ich als Info für @Asgothian gedacht

[hydrotec]

@homoran sagte in [Doku] Themensammlung zu MQTT allgemein:

schön jetzt auch die drei Befgriffe noch erklärt zu haben.

In der Zwischenzeit hatte ich die Grafik noch einmal angepasst.
Jetzt habe ich keinen Platz mehr. ;-)
Ich werd mir das noch einmal ansehen, vielleicht fällt mir noch was anderes ein.

@homoran sagte in [Doku] Themensammlung zu MQTT allgemein:

Der Hintergrund ist, dass im RAW Modus auch der Inhalt noch lesbar bleiben soll und nicht 280Zeichen je Zeile enthält.

Das kann ich auch verstehen, doch warum nur 80 Zeichen, ich find das schon etwas wenig.
Und wenn ich mir die ein oder andere Seite auf GitHub ansehe, da werden durchaus mehr Zeichen pro Zeile verwendet.
Deswegen wundert mich das etwas, und ich möchte es auch nicht einfach nur ignorieren.
Schließlich handelt es sich ja um eine offizielle Dokumentation.

EDIT:
Wieviele Zeichen sind denn in der offiziellen Doku mmöglich, bevor ein automatischer Zeilenumbruch stattfindet.
Weiss das zufällig jemand?

[Homoran]

@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:

Das kann ich auch verstehen, doch warum nur 80 Zeichen, ich find das schon etwas wenig.

nö, das ist je nach abgebildeter Schriftgröße, die übliche Zeilenlänge

Das Problem im Moment ist, dass es bei einem einfachen Umbruch auch in der Ansicht umbricht, was nicht passieren sollte.

Arbeitest du mit Apfeln?

[hydrotec]

@homoran sagte in [Doku] Themensammlung zu MQTT allgemein:

Arbeitest du mit Apfeln?

Nein, mit Fenster.
Bzw. direkt auf GitHub.

[Homoran]

@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:

@homoran sagte in [Doku] Themensammlung zu MQTT allgemein:

Arbeitest du mit Apfeln?

Nein, mit Fenster.
Bzw. direkt auf GitHub.

:thinking_face:
Auch nur mit einem einfachen Enter?
ohne STRG oder sonstwelchen Luxus???

Müsste so aussehen

[hydrotec]

@homoran

Spätestens nach 80 Zeichen in einer Zeile setze ich doppeltes Leerzeichen für den Zeilenumbruch.

[Homoran]

@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:

setze ich doppeltes Leerzeichen für den Zeilenumbruch.

das ist der Fehler!

einfach <ENTER>

[hydrotec]

@homoran

OK, verstanden.
Dann habe ich wohl den Hinweis in der Style Dokumentation missverstanden.
Werde alles noch einmal umformatieren.
Geht ja schnell ;-)

[Asgothian]

@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:

Ich hatte versucht, mich weitestgehenst an die Styleguide Dokumentation zu halten.
Und so wirklich glücklich bin ich mit der jetzigen Formatierung auch nicht.
Wie ich ja schon einmal erwähnt hatte, sind das meine ersten Gehversuche zu Markdown.
Wenn es dir nichts ausmacht, und du die Zeit dafür hast, könntest du mir bitte ein Beispiel zur Verfügung stellen,
wie du das umsetzen würdest. Also nicht die ganze Seite, nur ein zwei Blöcke, für mich zur Vorlage.
Gerne direkt in der von mir erstellten Doku.
Letztendlich soll es ja allen hilfreich sein, und ich kann mich zu Markdown weiterbilden.
Vorab schon ein Dankeschön.

Mach ich, aber erst heute Abend.

A.

[hydrotec]

@asgothian sagte in [Doku] Themensammlung zu MQTT allgemein:

Mach ich, aber erst heute Abend.

Wie du Zeit hast, Danke

[Homoran]

@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:

Dann habe ich wohl den Hinweis in der Style Dokumentation missverstanden.

Anscheinend.
Der Zeilenumbruch sollte im RAW zu sehen sein, damit es dort nicht zu unendlichen Zeilenlängen kommt.
80 Zeichen ist auch nicht wirklich in Stein gemeißelt

[hydrotec]

@homoran
OK, hab die Doku noch einmal etwas angepasst.
Jetzt sieht es auch für mich besser aus.

@Asgothian
Für den Fall, das du das mit der Formatierung gemeint hast, dann hat es sich wohl erledigt.
Solltest du dennoch Verbesserungen vornehmen wollen, gerne doch.

Bin für jeden Hinweis dankbar.

So, jetzt erst einmal Mittagspause ;-)
Angenehmen Nachmittag noch.

[Asgothian]

@hydrotec sagte in [Doku] Themensammlung zu MQTT allgemein:

Für den Fall, das du das mit der Formatierung gemeint hast, dann hat es sich wohl erledigt.
Solltest du dennoch Verbesserungen vornehmen wollen, gerne doch.
Bin für jeden Hinweis dankbar.

Es hat sich zum Teil erledigt. Die seltsamen Zeilenumbrüche sind weg, die fehlende Strukturierung fehlt immer noch und sprachlich gibt es immer noch einiges an Stolpersteinen, i.e. Formulierungen die man bei einem Gespräch so anwenden würde, die aber in einem Text fehl am Platz sind. Als Beispiel nur dieses:

"Diese Struktur wird meistens von den Herstellern vorgegeben, kann jedoch ebenso von Anwendern definiert werden. Kommt darauf an, um was für eine Art von Gerät es sich handelt."

Und auch wenn es kleinlich erscheint - es sind viel zu viele Kommata im Text :)

Ich geh da heute Abend mal drüber.

A.

[Homoran]

@asgothian sagte in [Doku] Themensammlung zu MQTT allgemein:

Ich geh da heute Abend mal drüber.

Bitte bedenkt aber, dass diese "Vorgaben" formal zwar korrekt sind, in Bezug auf die geplante Leserschaft aber nicht zu stark in unverständliches Fachchinesisch gewandelt werden sollte.