Grundidee der Themenausrichtung der Doku

[Muchul]

Kurze Anmerkung zu markdowns, wird bei uns im Intranet eingesetzt.
Leider findet dann die Suche nichts, wenn es zugeklappt ist.
In dem Beispiel auf GitHub ist es auch so. Versuche ich mit strg f etwas zu finden, wird kein Treffer angezeigt.
Ist für dieses Problem eine Lösung bekannt?

Und nein, eine bessere idee habe ich auch nicht zu bieten.

[Homoran]

@muchul sagte in Grundidee der Themenausrichtung der Doku:

Ist für dieses Problem eine Lösung bekannt?

alles aufklappen und dann suchen

Spaß beiseite!
Danke für den Hinweis

[Muchul]

@homoran sagte in Grundidee der Themenausrichtung der Doku:

alles aufklappen und dann suchen

Das war tatsächlich ein Argument, was vorgebracht wurde, aber das weiß ein Besucher ja nicht.

Da wäre eventuell noch die Möglichkeit einer langen Seite.
Oben kurz und Details unten. Oben dann Sprungmarken nach unten zu den weiterführenden Informationen.
Optimalerweise dann unten wieder Sprungmarken zum Text oben, von wo man gekommen ist.
Unten sollten die Themen die gleiche Reihenfolge wie oben haben.

[hydrotec]

Ich hätte eine Frage, bezüglich der Einsortierung eines Themas, in den vorhandenen Kategorien der Doku.

Es handelt sich um das Thema "MQTT", zu dem ich gerade dabei bin, eine Dokumentation zu erstellen.
https://forum.iobroker.net/topic/51763/mqtt-broker-client-adapter

In welcher Kategorie würdet ihr das Thema "MQTT" einordnen,
unter "Grundlagen", "Erweiterte Konfiguration", oder in einer anderen Kategorie?

Vorab schon einmal Dankeschön für eure Hilfe.

[Muchul]

Naja, das ist schwierig.
MQTT stellt ja nur Informationen bereit die von anderer Stelle zur Verfügung gestellt werden.
Ich würde zweiteilen:
Einmal wie der Adapter eingerichtet wird und im erweiterten Teil dann tiefer gehende Grundlagen wie MQTT funktioniert.
Ohne diese Grundlagen ist der Adapter ja so gut wie nicht nutzbar.

Ich habe beispielsweise erst durch versuche rausgefunden das Datenpunkte erst angelegt werden wenn ich sie anderweitig publiziere.

[Andreios]

@apollon77 sagte in Grundidee der Themenausrichtung der Doku:

Diese Zielgruppen würde ich mal grob wie folgt einteilen:

• Interessenten: haben von ioBroker gehört oder kommen per Google und wollen schauen/verstehen was das Ding tut und kann. Da geht es also um "kurz und knackig", bissl "Marketing" darf auch dabei sein und 100% Korrektheit in allen Fakten braucht es vllt nicht immer

Das kann man zwar in der Doku noch einmal berücksichtigen, aber "kurz und knackig" dem Interessenten ioBroker nahe bringen sollte IMHO schon die Startseite https://www.iobroker.net/!
Ich finde die Startseite zwar grundsätzlich gut, aber bei "Über ioBroker" finde ich das zu technisch für den Laien.
Bis zu diesem Post habe ich mir da keine Gedanken drüber gemacht, weil ich vorher schon mit FHEM und Hass Erfahrung hatte und technisch nicht ganz unbedarft bin, aber bei Laien in solchen Systemen kann ich mir vorstellen, dass man das verlockender beschreiben kann. (Ich eher nicht, weil ich es zu technisch sehe. )

[Andreios]

@apollon77 sagte in Grundidee der Themenausrichtung der Doku:

• Tutorials: Ja wie der Name sagt für Einsteiger und Benutzer, ggf auch Interessenten zum überfliegen

Gerade das ist der auffallendste Punkt! Diese ganzen Unterpunkte "Tutorial" mit dem Inhalt "Das ist ein Platzhalter" sollten sofort verschwinden!
Wie sieht das denn aus, wenn da, seit offensichtlich langer Zeit, sich die Platzhalter nicht füllen und nur ein einziges Tutorial vorhanden ist?
Das eine Tutorial kann auch in die ganz normale Doku verschoben werden.
Es gibt auch noch andere Platzhalter, nicht nur bei den Tutorials.
Dadurch sieht das Menü zwar schön groß aus, aber der Informationsgehalt ist gering und frustriert den Leser.

Es ist zwar schön, wenn Tutorials vorhanden sind, weil der Begriff heute modern ist, aber eigentlich ist es dann ja doppelt gemoppelt, wenn es eine Doku gibt, wo beschrieben wird, was man machen kann und dann dazu auch noch an einer zweiten Stelle ein Tutorial. btw: Ich finde, das Tutorial "Adapter verwalten" ist genauso gut eine Doku.

[Jey Cee]

@hydrotec sagte in Grundidee der Themenausrichtung der Doku:

In welcher Kategorie würdet ihr das Thema "MQTT" einordnen,
unter "Grundlagen", "Erweiterte Konfiguration", oder in einer anderen Kategorie?

MQTT ist nicht ioBroker Spezifisch, sondern ist ein Thema was von Adaptern in ioBroker gebracht wird. Konsequenterweise gehört es damit in die Dokumentation der jeweiligen Adapter.
Will man das Thema dennoch in den Allgemeinen Teil Aufnehmen, was ich für absolut falsch halte, sollte dafür eine Kategorie geschaffen werden die ganz Klar macht das es sich nicht um einen Bestandteil von ioBroker handelt.

Sonst wird fälschlicherweise erwartet das wir Fehler beheben oder Support für MQTT leisten, da es ja zu ioBroker gehört.

Dieses Problem haben wir schon bei den Adaptern, es werden immer wieder Fehler gemeldet die gar nicht vom Adapter selbst kommen, aber die User erwarten das sie behoben werden.
Das muss man dann jedesmal wieder erklären.

[Andreios]

@apollon77 sagte in Grundidee der Themenausrichtung der Doku:

Macht das Sinn?

Unabhängig von den 2 Punkten, zu denen ich schon etwas geschrieben habe:
Ich finde es gut und richtig, sich mit der Doku, im Dialog mit den (auch potentiellen) Anwendern, ständig auseinanderzusetzen.

Ohne dies finde ich es schwierig, allen die richtigen Informationen zu geben.

Eine Beschränkung auf einfachen Aufbau, so wie auch schon, vielleicht anders formuliert, in anderen Antworten zu lesen, finde ich wichtig, also nicht Doku + Tutorials + FAQ! Da ist der unbedarfte Leser schnell überfordert, wenn er einmal etwas gefunden hatte und es wieder sucht und muss dann erst schauen, ob es Doku oder Tutorial oder FAQ war.
Also einfacher Aufbau mit Grundlagen, Installation und dann der Rest in gut abgegrenzten Artikeln finde ich wichtig.
Dann die weiteren Informationen in Untermenüs (mein Favorit) und/oder in Links im Text zu den Vertieferthemen (Nicht so mein Favorit, weil dann die Übersicht schnell verloren geht, weil man für den nächsten Link im Text wieder zurück auf die Ursprungsseite muss um dann den nächsten zu klicken. Vielleicht aber einfach oben oder unten Links auf die nächste und vorherige Seite zu dem Thema.).

[Andreios]

@jey-cee sagte in Grundidee der Themenausrichtung der Doku:

@hydrotec sagte in Grundidee der Themenausrichtung der Doku:

In welcher Kategorie würdet ihr das Thema "MQTT" einordnen,
unter "Grundlagen", "Erweiterte Konfiguration", oder in einer anderen Kategorie?

MQTT ist nicht ioBroker Spezifisch, sondern ist ein Thema was von Adaptern in ioBroker gebracht wird. Konsequenterweise gehört es damit in die Dokumentation der jeweiligen Adapter.
Will man das Thema dennoch in den Allgemeinen Teil Aufnehmen, was ich für absolut falsch halte, sollte dafür eine Kategorie geschaffen werden die ganz Klar macht das es sich nicht um einen Bestandteil von ioBroker handelt.

Sonst wird fälschlicherweise erwartet das wir Fehler beheben oder Support für MQTT leisten, da es ja zu ioBroker gehört.

Dieses Problem haben wir schon bei den Adaptern, es werden immer wieder Fehler gemeldet die gar nicht vom Adapter selbst kommen, aber die User erwarten das sie behoben werden.
Das muss man dann jedesmal wieder erklären.

Das man das immer wieder erklären muss, wird sich IMHO durch nichts ändern!
Auch eine Kategorie, die das verhindert, kann nicht erschaffen werden!
Allerdings ist es für den Anwender auch schwierig, wenn manche Adapter dann doch in der Doku sind, z.B. vis.

Ansonsten bin ich auch der Meinung, dass dies in die Adapterbeschreibung gehört und damit auch die größtmögliche Abgrenzung hat!

[apollon77]

@hydrotec ganz spontan (ohne die schon geposteten Antworten gelesen zu haben): Doku beim Adapter ... ob man in den "allgemeinen teil" der Doku mal noch einen "wichtige iOT Protokolle und wie ioBroker diese Unterstützt" oder so mache ist mal ne andere Idee - dann wäre Mqtt generell dort dabei aber mit dann Links zu den Details "beim Adapter" ... my opinion

[Homoran]

@andreas-5 sagte in Grundidee der Themenausrichtung der Doku:

Diese ganzen Unterpunkte "Tutorial" mit dem Inhalt "Das ist ein Platzhalter" sollten sofort verschwinden!

Was soll jetzt diese plakative Aussage?
Das nutz niemandem etwas

Genau deswegen sitzen wir ja hier dran!

@andreas-5 sagte in Grundidee der Themenausrichtung der Doku:

Dadurch sieht das Menü zwar schön groß aus, aber der Informationsgehalt ist gering und frustriert den Leser.

Dann hast du wahrscheinlich dieses hier nicht gelesen https://forum.iobroker.net/topic/51731/grundlagen-der-struktur-hinter-der-doku und auch noch nie davon gehört, dass aus technischen Gründen das Menü im Vorfeld errichtet werden musste

[OstfrieseUnterwegs]

@apollon77 Genau, herstellerübergreifende Standards und Protokolle: mqtt, zigbee, z-wave, knx, ... und wie diese sich integrieren kurz beschreiben und dann die Details bei den einzelnen Adaptern.

BTW: Alias ist im Moment irgendwo unten bei Adapterentwicklung. Imho ist das ein zentrales Konzept und sollte entsprechend prominent beschrieben werden

[Homoran]

@ostfrieseunterwegs sagte in Grundidee der Themenausrichtung der Doku:

BTW: Alias ist im Moment irgendwo unten bei Adapterentwicklung. Imho ist das ein zentrales Konzept und sollte entsprechend prominent beschrieben werden

korrekt!
wurde auch schon ausgiebig diskutiert

[hydrotec]

@Jey-Cee
@Andreas-5
@apollon77
@OstfrieseUnterwegs

Danke erst einmal zu euren Gedanken.

Der Grundgedanke, MQTT in die offizielle Doku mit aufzunehmen, war,
dem Interessenten/Einsteiger in einer groben Ausführung, zu dem Thema eine kleine Hilfestellung zu geben.

• kurze Beschreibung was MQTT überhaupt ist, mit Links zu themenbasierten Webseiten.
  (z.B. mqtt.org, Wikipedia, usw.)
• Vorstellung welche Adapter zur Verfügung stehen,
  und welchen man am Besten zu einer bestimmten Konstellation nehmen könnte.
  ioBroker kann ja auch als MQTT-Broker verwendet werden, und damit externe Broker wie z.B. mosquitto ablösen.
  Zusätzlich Links zu den jeweiligen Adaptern
• kleiner Hinweis, was Topics sind, und wie das Zusammenspiel mit ioBroker funktioniert.
• Eventuell noch eine kleine Sammlung zu Tutorials, welche sich mit diesem Thema beschäftigen.

Also wirklich nur kurz umschrieben.
Die ausführliche Dokumentation zu einem Adapter gehört auch dort hin.
Da bin ich voll bei euch.
Mir ist eben aufgefallen, das zum Thema MQTT doch immer wieder Fragen im Forum auftauchen,
und die Lösungswege sich meistens wiederholen.

Vielleicht gibt es noch einen anderen Weg, nicht unbedingt in der Doku,
das ein Interessierter/Einsteiger einen ersten Anlaufpunkt bekommt.

Gruß, Karsten

[apollon77]

@ostfrieseunterwegs sagte in Grundidee der Themenausrichtung der Doku:

@apollon77 Genau, herstellerübergreifende Standards und Protokolle: mqtt, zigbee, z-wave, knx, ... und wie diese sich integrieren kurz beschreiben und dann die Details bei den einzelnen Adaptern.

So eine Seite haben wir noch nicht...müsste man mal überlegen wo man das in die Struktur einsortiert, aber ja könnte für Interessenten vor allem interessant sein ...

[Homoran]

@apollon77
Da muss man aber genau das Thema wie weit wir als ioBroker in diese Materie einsteigen sollten, überdenken. Ich erinnere mich noch an die Zeit als in dem Forum sehr viele Fragen zu node-red kamen, die ich nicht einordnen konnte. Da stellte sich dann immer heraus, das es gar keine ioBroker-User waren, sondern node-red standalone.

In dem Bereich unterstütze ich dann die Idee zur Verlinkung externer Seiten.
Was für ioBroker interne Dinge ein noGo ist, sollte für tiefergehende Grundlagen eines externen "Systems" durchaus legitim sein, da wir nur die Integration "zu verantworten" haben.

Es sollten also nur kurze Worte zum Funktionsprinzip und ein Link zu einer tieferen Beschreibung in der Einleitung der Doku stehen.
So hatte ich es bei node.red damals gemacht: https://www.iobroker.net/docu/index-280.htm?page_id=4284&lang=de Man möge mir diesen Uralt-Link verzeihen!

Und dann gehört so etwas der Rest in die Adapterreferenz.

Überspitzt gesagt:
Wenn wir die ioBroker-Doku zu einem SmartHome-oder gar IT-Wiki anheben wollen, müssen wir uns das sehr gut überlegen.
Dann brauchen wir u.a. wesentlich mehr aktive Dokumentatoren, die sich auf Einsteigerniveau einstellen können und trotzdem das notwendige Fachwissen beherrschen.
Von Struktur und Platz mal ganz abgesehen

[hydrotec]

@muchul sagte in Grundidee der Themenausrichtung der Doku:

Ich habe beispielsweise erst durch versuche rausgefunden das Datenpunkte erst angelegt werden wenn ich sie anderweitig publiziere.

Hallo Muchul,

ich lade dich herzlichst ein, in diesem Thread deine Erfahrungen mitzuteilen.
Je mehr Informationen in dem Thread enstehen, desto zielgerechter kann ich die Doku zu MQTT aufbauen.

Danke
Gruß, Karsten

[apollon77]

@homoran Nee das will ich ja gar nicht ... Bin voll bei dir ... wenn dann maximal die "Buzzwords" (und ein Satz das der Kontext klar ist)) und links an die richtigen stellen ... Wenn man sowas will.

Am Ende ist die "Logik und Automatisierung"-Startseite genau so ein Bereich. Hier sollten Abschnitte sein über "Scenes", "JavaScript" mit den Regelformen Rules, Blockly, Skripte und am Ende auch Node-Red. Ggf jeweils ein Screenshot und ein Kurzer Absatz was zeigt was da geht und "wie einfach das ist" und dann idealerweise Links zu mehr und spezifischem Kontext.

Für andere Dinge müsste an noch eine Seite erstellen wo man andere "relevante iot Themen" auf ebenso eine Art dann ggf ohne bilder) darstellt und Links setzt

[Homoran]

@apollon77 sagte in Grundidee der Themenausrichtung der Doku:

Am Ende ist die "Logik und Automatisierung"-Startseite genau so ein Bereich. Hier sollten Abschnitte sein über "Scenes", "JavaScript" mit den Regelformen Rules, Blockly, Skripte und am Ende auch Node-Red.

Genau - da passt dann z.B. node-red hinein.

Aber diese Diskussion hatten wir bei Zigbee und jetzt bei MQTT - also Protokolle
Ich muss mir nochmal die "Struktur hinter der Doku" ansehen, ob da nicht auch schon was geplant war, oder ob das nur eine Kategorie bei den Adaptern geworden ist