Grundidee der Themenausrichtung der Doku
-
Hi auch von mir,
da ich an der groben Themenstruktur der (leider) teilweise noch eher schlecht gefüllten Seiten nicht unschuldig war hier auch noch ein bissl Kontext von mir.
Die Doku in der Webseite hat die Challenge verschiedene Zielgruppen abzudecken. So richten sich verschiedenen Bereiche der Webseite auch an verschiedene Zielgruppen.
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
- Einsteiger: Sind die, die wirklich erste Schritte mit ioBroker machen
- Benutzer: Nutzen es aktiv, also nach den ersten Schritten
- Fortgeschrittene: Nutzen es länger und fangen an nicht mehr Standarddinge tun zu wollen
- Power-User: Hier sind wir schon weiter weg vom Standard
Jetzt könnte man fleissig über Details hierzu streiten und wer was ist und was will, aber ich denke als grobe Einstufung reicht es erstmal (und ja die Zielgruppen haben große Überschneidungsbereiche, was aber auch ok so ist).
Bevor jetzt eine Diskussion wegen dem Begriff "Marketing" aufkommt: Am Ende gibt es mehrere (Open Source) Smart-Home-Systeme: Neben ioBroker sind das als Open Source OpenHab, Hass und FHEM und noch einige kleinere und dann viele kommerzielle Alternativen wie Homey, Homee und und und. Damit müssen wir als Open Source Projekt genauso "Marketing" machen warum ioBroker das geilste der Projekte ist und warum ein User sich dafür entscheiden soll
Es gehört für das "Gesamtprojekt" "Webseite und Doku", um die es hier geht, meiner Meinung nach eindeutig mit dazu.Jetzt zu den ersten "Seiten" und der groben Idee dahinter (gern als Diskussionsgrundlage wobei wir mal schauen müssen "wie" wir das am besten diskutieren):
- Willkommen: Naja wie es sagt willkommen; vor allem aber Interessenten und Einsteiger abholen und "Leiten" (alle anderen klicken da eh nicht mehr hin)
- Grundlagen: Überblick für Interessenten und generelles Verständnis von "den zentralen Begrifflichkeiten" die man braucht (und nein ist kein Glossar) Aber heir kurz und knackig und gern bissl "Marketing" machen. Wenn man es "genau" erklären will dann bitte die Seite zweistufig machen ... oben "TLDR;" style und gern Details weiter unten und auch klar gekennzeichnet das es hier "genauer" wird (oder vllt direkt auf einer Unterseite), sonst vergrault man Interessenten weil es so komplex wird Da müssen wir noch eine "sinnvolle Form finden"
- Installation: How to install, Für Interessenten mit "ist ja ganz easy"-Message und für Einsteiger halt als "How to".
- Admin-Oberfläche: Dieser Bereich soll nicht eine Admin-Doku ersetzen! Sie soll für Interessenten und Einsteiger zeigen wie das ganze aussieht und quasi bei den ersten Schritten helfen um nen Überblick zu bekommen. Für mehr dann zur Admin Doku (die auch noch todo ist) verlinken
- Tutorials: Ja wie der Name sagt für Einsteiger und Benutzer, ggf auch Interessenten zum überfliegen
- Visualisierungen: Hauptseite bzw die "typen der visus"-Unterseiten ist wieder für Interessenten damit sie sehen was geht, und je tiefer umso spezifischer und ggf für die anderen Zielgruppen ... Zu DOku der Visus verlinken
- Logik und Automatisierung: ebenso: beginn mit Überblick was geht für Interessenten und Einsteiger, "je tiefer" umso spezifischer für die anderen
- Cloud Services & Apps: das gleiche
- Erweiterte Konfiguration: Jetzt startet es mit dem was ggf nicht alle tun oder brauchen, also geht es mit "Benutzern" als Ziegruppe los ... und am Ende alle
- Fehlerbehebung: Ab Benutzer, am Ende die Standard Troubleshooting Themen
- FAQ: Ab Benutzer am Ende des Tages, idealerweise dort schauen bevor man Issues öffnet oder im Forum postet
- Unterstützung: Wie kann man als User das Projekt unterstützen
- Adapterentwicklung: verschwindet als Content und ist später nur noch ein Link zur Dev-Doku
- Systemintegratoren: Da geht es Richtung kommerzieller Nutzung ... würde ich hier auch mal ausklammern.
Macht das Sinn?
-
@apollon77
Danke!
besser hätte ich es auch nicht schreiben können.
Die Gruppe Interessierte war für mich immer ganz entscheidend, hatte sie aber (auch im Geiste) gar nicht von Einsteigern getrennt
@apollon77 sagte in Grundidee der Themenausrichtung der Doku:
Wenn man es "genau" erklären will dann bitte die Seite zweistufig machen
wie bereits geschrieben habe ich diesen Ansatz schon seit langem verfolgen wollen. Leider fehlten mir die technischen Voraussetzungen dafür.
Ein Snippet von @Crunchip habe ich testweise mal auf dieser Seite ganz unten installiert:
https://github.com/ioBroker/ioBroker.docs/tree/master/docs/de/tutorialin der Doku wird es hoffentlich im nächsten Build zu sehen sein.
Muss mich nur noch damit beschäftigen, wie das ausgebaut werden muss, damit der "Fortgeschrittenenteil" dann auzuklappen geht.So sollten wir das dann IMHO mit Dingen machen, die den Lesefluss von Einsteigern stören könnten.
Auf GitHub funktioniert das schon:
-
@homoran Für "weiterführende Infos" vllt aber auch/einfacher mit Unterseiten arbeiten und dann verlinken? ALso ja "Linkliste aufklappbar" vllt oder so
Und ja wenn wir feststellen das wir noch "Fortgeschrittene Bereiche" brauchen dann vllt lieber da mal noch nen neuen Hauptpunkt machen ?
-
@homoran sagte in Grundidee der Themenausrichtung der Doku:
Die Gruppe Interessierte war für mich immer ganz entscheidend, hatte sie aber (auch im Geiste) gar nicht von Einsteigern getrennt
Naja der Unterschied ist für mich klar: Interessenten müssen wir bei der Entscheidung helfen, Einsteigern muss man beim Einstieg und den ersten Schritte helfen und dabei sich "bei uns" zurechtzufinden damit Sie nicht gleich wieder abspringen
-
@apollon77 sagte in Grundidee der Themenausrichtung der Doku:
mit Unterseiten arbeiten und dann verlinken?
Das wäre auch eine Möglichkeit, ist aber nicht mein Favorit.
Mit Unterseiten würde ich nur bei sehr großen Inhalten arbeiten -
@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.
