Grundidee der Themenausrichtung der Doku
-
@apollon77 Unterseiten sind teilweise durchaus sinnvoll.
Aber in den Bereichen "Interessierte" und "Einsteiger" sollte das "Klickaufkommen" nicht zu hoch werden. Dann wird es wieder unübersichtlich. Das verhindert dann das weiterlesen. Dann sollte eher in der nächsten Stufe mehr ins Detail gegangen werden.
Man könnte ja hier eventuell mit Links im Fließtext arbeiten um Detailinformationen hervorzuheben die aber nur auf Bedarf aufgerufen werden (in der Einsteigersektion).Im Bereich Fortgeschrittene kann dann durchaus mit Unterordnern gearbeitet werden. Das erleichtert dort die Suche.
Der Punkt "Interessierte" und "Einsteiger" finde ich ungeheuer wichtig. Ich kann mich noch gut erinnern wie ich mir mühevoll stundenlang alles zusammengeklaubt habe was mich zu einer Entscheidung geführt hat. Da war der ioBroker ursprünglich recht weit hinten in der Auswahl mangels Informationen.
Erst durch deutliche Empfehlungen von Anderen bin ich dann hier gelandet. -
@chaot sagte in Grundidee der Themenausrichtung der Doku:
Man könnte ja hier eventuell mit Links im Fließtext arbeiten um Detailinformationen hervorzuheben die aber nur auf Bedarf aufgerufen werden
so hatte ich das auch verstanden, bzw hätte ich das so umgesetzt.
deswegen würde ich nicht für eine kurze Zusatzerklärung auf eine Unterseite verlinken, sondern mit einer "read more" Funktion am Ende des Absatzes arbeiten.
Das sollte dann den Lesefluss auch nicht stören. -
Vllt könnten wir am Beispiel des PRs von @paul53 (Danke dafür!) mal überlegen bzw exemplarisch bauen wie es aussehen könnte ... das ist hier grad ein interessantes Beispiel.
https://github.com/ioBroker/ioBroker.docs/pull/352/files
In meinen Augen bräuchten wir am Anfang einen Abschnitt was "Rollen" überhaupt sind und wozu Sie da sind.
Der Haupt-teil des PRs wäre "wenn du als user selbst ein Objekt anlegst dann gibt es folgende Rollen" was in dem Fall quasi ein "Duplikat" aus der Developer Doku ist ... wat machmer denn da?
closed Update roles.md #352
-
@apollon77 sagte in Grundidee der Themenausrichtung der Doku:
quasi ein "Duplikat" aus der Developer Doku ist ..
ich hatte mich gerade gefragt warum Rollen hier in der Userdoku interessant sein könnten
-
@homoran sagte in Grundidee der Themenausrichtung der Doku:
ich hatte mich gerade gefragt warum Rollen hier in der Userdoku interessant sein könnten
Naja die sind schon wichtig wie gesagt für den Fall das User eigene Objekte zB via Admin oder JavaScript anlegen - das machen viele!!
-
@apollon77 Interessantes Beispiel. Ganz speziell was auch die Übersichtlichkeit angeht.
Da das im "Pro-Bereich" wäre würde ich hier auch mit Unterordnern arbeiten. Zumal das dann übersichtlicher wird ohne lange zu scrollen.Einleitung
-
Rollen (Allgemein, Sensor usw,)
- einzelne Rollen
(sorry Das mit dem Formatieren hier ist grauenhaft)
-
-
@chaot sagte in Grundidee der Themenausrichtung der Doku:
würde ich hier auch mit Unterordnern arbeiten
damit meinst du einen weiteren Unterpunkt im Menü erzeugen?
Lies bitte hier:
https://forum.iobroker.net/topic/51731/grundlagen-der-struktur-hinter-der-dokuund sieh dir das an:
https://github.com/ioBroker/ioBroker.docs/blob/master/engine/front-end/public/content.json -
@homoran sagte in Grundidee der Themenausrichtung der Doku:
Ein Snippet von
Ich hatte das hier gefunden und auch gleich verwendet bei doku-nodejs update
-
@crunchip Dann bin ich mal gespannt wie das im Doku-Framework funktioniert, wenn mein Test im nächsten Build da reinrutscht
-
@crunchip Ja, genau so habe ich das gemeint.
Also Dropdown sogar noch besser als die Unterordnerlösung. -
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.
-
@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 -
@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. -
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-adapterIn 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.
-
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.
-
@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.
) -
@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.
-
@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. -
@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.). -
@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!
