Strukturierungsversuch Doku - Allgemein
-
Auslöser für diesen Thread war ein Thread von @apollon77
https://forum.iobroker.net/topic/49316/strukturierungsversuch-dokumentationWenn jetzt daber die Struktur sowieso angepackt wird, wäre es sinnvoll diese Umstrukturierung nicht nur im Developer-Teil durchzuführen.
Feedback dringend erwünscht!
@apollon77 Ich denke wir sollten dieses Thema ggf. auch in mehrere Unterthemen runterbrechen - vielleicht aber auch erst später.
Dann sollten wir vorher (also jetzt
) überlegen was die Top-Level Themen sein sollten und dann später diese in einzelnen Threads verfeinern.Top-Level in dem Sinne wie du sie schon geschrieben hast. (vielleicht noch mit Top-Top-Leveln)
-
Allgemeines
- Was ist ioBroker
- Wie ist ioBroker aufgebaut
- Wo finde ich die verschiedenen Quellen
- Hilfestellungen
- Forum
- Was braucht ein Helfender an Informationen
- GitHub
- Issue erstellen (oder gehören diese Punkte unter "Fehlersuche" weiter unten?)
- Forum
-
Glossar/Erklärungen
-
Enduser
- Einsteiger
- ???
- Tutorials
- Fortgeschrittene
- ???
- Installation (wirklich auf dem Level?
- Fehlersuche
-
Developer
Wie ihr seht geht es damit schon einmal los
Daher wäre es schön, wenn sich die Einsteiger auch dazu äußern würden, wo sie nach was für Informationen suchen würden. -
-
@homoran Gern, aber das sollten wir in einen zweiten Thread machen. Diese Übersicht ist entstanden als vom "Aufhänger" Entwickler-Doku (meiner Meinung nach) immer wieder andere Themen reingemischt wurden und auch die "Idee der aktuellen Struktur" nicht so bekannt zu sein schien ... daher mein Versuch es mal zu strukturieren/zusammenzufassen ...
Idee wäre: Hier machen wir "Strukturdiskussion generell" ... dann gern Unterthreads für die Einzelnen größeren Bereiche
Ok? -
Wenn die Doku jetzt mit mehr Leben gefüllt werden soll, dann muss man sich zuerst die Frage stellen für welche Zielgruppe man zuerst die Doku sauber aufsetzt. Hier sollte man sich auf eine Zielgruppe festlegen und für diese die Inhalte füllen bevor man zur nächsten Zielgruppe geht.
Mein Vorschlag für der Zielgruppen inkl. Reihenfolge wie man die Doku mit Leben füllen sollte:
a) Besucher
b) Anfänger / Erste Inbetriebnahme
c) Anwender
d) EntwicklerHier sind meine Gedanken, was ich aus der Sicht eines Besuchers / Anfängers von einer Doku erwarte bzw. zu welchen Themen ich in einer Doku anfangen würde zu lesen.
Die Nachfolgenden Unterpunkte stellen Inhalte dar, welche ich in der Hauptkategorie erwarten würde:
-
Übersicht über ioBroker
-- Was ist die Kernaufgabe von ioBroker
-- Welche Geräte / Anwendungen / Dienste werden von ioBroker mit Hilfe von Adapter unterstützt
-- Ausblick ioBroker Cloud Services
-- Individuelle Erweiterbarkeit durch den Einsatz von Skripten
-- Beispiele von Anwendungsgebieten in denen ioBroker eingesetzt wird
-- Kosten
-- Was benötigt man für den Einsatz von ioBroker (Hardware auf der ioBroker läuft, ggf. Bridges für andere Systeme wie HomematicIP, Zigbee, Hue Bridge)
-- Anwendungsbeispiele / Showroom
-- Wer steckt hinter ioBroker (Core Team, Developer, Community) wo wird ioBroker entwickelt
(Github, Opensource) -
Installation und Wartung
-- Auf welcher Hardware kann ioBroker installiert werden
-- Wie installiere ich ioBroker auf den einzelnen Zielplattformen
-- Wie installiere und aktualisiere ich Adapter (inkl. der Beschreibung welche Möglichkeiten und Quellen es gibt mit den entsprechenden Risiken)
-- Wie erstellt man Backups und stellt sie wieder her?
(-- Wie aktualisiert man den js-controller)
(-- Wie aktualisiert man node-js) -
Visualisierung
-- Welche Hardware kann für eine Visualisierung verwendet werden
-- Welche Unterschiedlichen Adapter gibt es (Vis, iQontrol, ...) und was sind die jeweiligen Stärken
-- Showroom Visualisierungen. Bei der Phoniebox gibt es einen Thread in Github https://github.com/MiczFlor/RPi-Jukebox-RFID/discussions/1330 wo die Bastler ihre Boxen zeigen. Ähnliches könnte man auch mit den Visualisierungen machen, wo jeder der möchte einfach 1 bis 2 Bilder von seiner Visualisierung einstellen kann und ggf. mit einem Link zum Forum wo über Details zur Visualisierung diskutiert wird. -
Probleme und Fehlersuche
-- Welche Informationen werden für eine Fehlersuche im Forum benötigt
-- Wo finde ich die ioBroker Logs inkl. Bereitstellung der Logs in Code-Tags im Forum
-- Verwendung von Github issus (Wer wertet die github issues aus, wie erstellt man ein issue)
Wenn ich so durch die aktuelle Doku gehe, dann wirken die vielen Platzhalter wie eine große Baustelle und es suggeriert, dass die Doku veraltet ist und nicht gepflegt wird. Wenn wir die Doku erweitern / mit leben füllen würde ich die ganzen leeren Seiten / Platzhalter rauswerfen, da sie keinen Informationsgehalt haben
-
-
@feuersturm da deckt sich vieles mit meinen Vorstellungen.
Ich gehe, wenn gewünscht, da gerne drauf ein wenn ich wieder am PC sitze.nur vorweg zu den Platzhaltern
Da bin ich auch ganz deiner Meinung. Das Problem ist, dass das Gerüst und der Inhalt über zwei Strukturen gepflegt wird.
Dahercwurde erst das Gerüst mit Platzhaltern gebaut, um es dann zu füllen.
Ich bin leider an dem Konzept verzweifelt...Was deinen Tonie-Vorschlag angeht bin ich dagegen, das in die Doku einzubauen, da die Pflege zu aufwändig wird.
Eine Vorstellung mit Link zum Forum, dort ggf ein eigener Bereich für so etwas, ist IMHO besser geeignet. -
@homoran sagte in Strukturierungsversuch Doku - Allgemein:
Was deinen Tonie-Vorschlag angeht bin ich dagegen, das in die Doku einzubauen, da die Pflege zu aufwändig wird.
Ich hätte hier einfach einen Github Post aufgemacht und dort kann dann jeder sein Bild reinladen. Dieser Faden wird dann einfach nur in der Doku verlinkt.
-
@feuersturm oder so!
Wobei nicht jeder User ein Freund von GitHub ist -
klingt im ersten Moment sehr vielversprechend,
so war, denke ich auch zur damaligen Zeit die Idee entstanden.
Grundgerüst...Platzhalter...hier und da mal etwas zusammengetragen, bisschen wurde nach und nach befüllt und lange wurde dann nichts mehr gemacht.
Sehr vieles veraltete, unvollständige oder gar nicht mehr anwendbare ist somit dort zu finden.wenn ich das so alles lese, ist das jede Menge Arbeit,
das ist nicht von heut auf morgen zu bewerkstelligen.So schnell wie die Entwicklung von Iobroker fortschreitet, kommt man da eigentlich kaum hinterher, das alles niederzuschreiben, geschweige denn aktuell zu halten.
Klar es gibt Themen, die sind von genereller Bedeutung,
wie z.b. Was ist IoBroker, paar Grundeinstellungen, Grundbefehle, etc..aber
gehts ans "eingemachte" bleibt man mit einer Beschreibung immer auf der Strecke
Das wir eine Never Ending Story -
@crunchip sagte in Strukturierungsversuch Doku - Allgemein:
So schnell wie die Entwicklung von Iobroker fortschreitet, kommt man da eigentlich kaum hinterher, das alles niederzuschreiben, geschweige denn aktuell zu halten.
ich kenne leute, die behaupten, das dokumentation auch bestandteil der entwicklung ist
-
@crunchip sagte in Strukturierungsversuch Doku - Allgemein:
und lange wurde dann nichts mehr gemacht.
deshalb ist der content ja auf github wo jeder, auch du hättest etwas beitragen können
-
@oliverio sagte: das dokumentation auch bestandteil der entwicklung ist
Das sollte sie sein, wird aber von Programmierern gern vernachlässigt.
-
@oliverio sagte in Strukturierungsversuch Doku - Allgemein:
@crunchip sagte in Strukturierungsversuch Doku - Allgemein:
So schnell wie die Entwicklung von Iobroker fortschreitet, kommt man da eigentlich kaum hinterher, das alles niederzuschreiben, geschweige denn aktuell zu halten.
ich kenne leute, die behaupten, das dokumentation auch bestandteil der entwicklung ist
das sollte definitiv für die Adapterreferenz so sein.
Bestandteil der Adapter und von dort in die Doku übertragen
Das ist auch der Hauptgrund warum die aktuelle Doku in Markdown ist. -
@crunchip sagte in Strukturierungsversuch Doku - Allgemein:
So schnell wie die Entwicklung von Iobroker fortschreitet, kommt man da eigentlich kaum hinterher, das alles niederzuschreiben, geschweige denn aktuell zu halten.
Klar es gibt Themen, die sind von genereller Bedeutung,
wie z.b. Was ist IoBroker, paar Grundeinstellungen, Grundbefehle, etc..
aber
gehts ans "eingemachte" bleibt man mit einer Beschreibung immer auf der Strecke
Das wir eine Never Ending StoryIch hätte daher die Doku auch vom "Groben zum Feinen" aufgesetzt. Die Themen die ich oben beschrieben habe legt man einmalig an und dann ist dort die Änderungsfrequenz eher gering.
Wenn ich mir die aktuelle Doku ansehe, dann ist bei einigen Seiten jedes Feld, jeder Button und jede Konfigurationszeile einzeln beschrieben. Das halte ich persönlich nicht für zielführend und wird darin enden, was du beschrieben hast, dass man nicht mehr hinterher kommt und es eine Never Ending Story wird.
-
@homoran sagte in Strukturierungsversuch Doku - Allgemein:
hättest etwas beitragen können
habe mich daran versucht
, bei Redis ,
aber man tut sich halt im allgemeinen sehr schwer etwas niederzuschreiben, wenn man nicht "vom Fach" ist.ich würde gerne mehr dazu beitragen,
hab mir immer wieder die "offenen" Punkte/ Platzhalter angesehen, überlegt/gerätselt was könnte man da rein schreiben, bzw was sollte da überhaupt rein.Aber dann irgendwie festgestellt, das macht so gar keinen Sinn, weil die Struktur einfach nicht passt, oder man beginnt mit einem Thema, beschreibt das näher, rutscht man automatisch schon wieder in einen anderen Bereich, der woanders besser aufgehoben wäre. Sprich, weil bestimmte Dinge "nahtlos" ineinander übergehen.
hoffe du verstehst was ich meine. -
@crunchip sagte in Strukturierungsversuch Doku - Allgemein:
hoffe du verstehst was ich meine.
sehr gut, weil ich auch
@crunchip sagte in Strukturierungsversuch Doku - Allgemein:
nicht "vom Fach"
bin.
Dier ersten beiden Dokus (github wiki, WordPress) habe ich ganz alleine nur durch trial and error sämtlicher Funktionen der damaligen Adapter geschrieben. Daraus dann auch die Installation und die ersten Tutorials.
@feuersturm sagte in Strukturierungsversuch Doku - Allgemein:
dann ist bei einigen Seiten jedes Feld, jeder Button und jede Konfigurationszeile einzeln beschrieben. Das halte ich persönlich nicht für zielführend
ist aber notwendig um einem Einsteiger zu helfen. Du weisst beim Schreiben nie, wo es bei jemandem anderen hängen wird.
Ganz aktuelles Beispiel https://forum.iobroker.net/topic/49338/doku-zu-datenpunkt-qualität/1@feuersturm sagte in Strukturierungsversuch Doku - Allgemein:
dass man nicht mehr hinterher kommt
Alleine die Screenshots für die jeweilige Adminversionen anzupassen war nachher schon ein Problem. Ich habe hier bestimmt schon wieder >100 Screenshots vorbereitet, als die nächste Versuon kam.
Da gibt es dann die Meldung im Forum: bei mir sieht alles anders aus!
und den Button hab ich nicht an der StelleAußerdem musste ich mich irgendwann entscheiden im Forum zu helfen (was IMHO auch eminent wichtig ist um dort das Feedback zu bekommen) oder täglich Stunden an der Doku zu schreiben.
-
Mal eine generelle Frage:
Ich selber habe Probleme in der Doku irgendetwas zu finden. Habe jetzt schon mehrfach gesucht in der Doku auf iobroker.net um die Konsolen-Befehle nochmal rauszusuchen um einen Adapter manuell zu stoppen oder bestimmte version zu installieren usw.
Bin ich zu blöd da was zu finden oder wie muss ich da suchen ? -
@segway suche und oder Filter auf der Seite benutzt?
https://www.iobroker.net/#de/documentation/config/cli.md -
@jey-cee
Ja klar habe ich alles gemacht. War klar dass es eine solche Seite gibt aber wie komme ich dahin ???
Ich gebe Konsole ein und kriege sowas hier und da ist nascht dabei:
-
@segway
bei mir klappt esaber das passiert, wenn content angelegt wird zu dem es keine Struktur gibt.
Da hätte auch die Struktur angelegt werden müssen. -
@segway ok der Suchbegriff liefert viel zu viele Ergebnisse, aber den Filter im Menü hast du nicht verwendet den der Liefert das gesuchte.
-
@homoran
Ja klar wenn man VORHER weiss dass man nach KONSOLENBEFEHLE suchen muss !
Das weiss doch aber niemand! Da gibt man nur Key Words ein wie Befehle oder Konsole / Console und dann kommt man damit NICHT zum Ziel.
Woher soll jemand Neues immer das Richtige Wort wissen um zum Ziel kommen ?
