NEWS
Strukturierungsversuch "Dokumentation"
-
Hi All,
ich weiss das die Kategorie nicht ganz passt, aber da heute in der Dev-Gruppe in Discord/Telegram eine Diskussion zum Thema "Dokumentation" aufgekommen ist, ist denke hier guter Startpunkt. Können wir ja noch verschieben.
In der Diskussion ist mir aufgefallen das wir mehrfach das "Thema" gewechselt haben. "Dokumentation" ist ein sehr großer Themenbereich und in meinen Augen gibt es hier verschiedene "Teilbereiche" die ggf auch andere Zielgruppen haben. Daher versuche ich hier einmal meine Sicht auf das große Thema zu geben und versuche es etwas zu strukturieren, wie ich es sehe. Damit wir uns dann in künftigen Diskussionen klar sind zu welchem "Teil" wir reden.
Als wir vor einiger Zeit die Dokumentation auf der Webseite (https://www.iobroker.net) neu gemacht haben steckt da durchaus ein Konzept dahinter. leider sind wir aktuell noch lange nicht damit fertig.
Hier genannte Themen kann man garantiert in sich auch nochmal kleiner brechen. Aber aus meiner Sicht ist eine Struktur bereits vorhanden - Sie muss "nur" noch mit Inhalt gefüllt werden
Generelle Projektdokumentation/-überblick
Zielgruppe: Interessenten, Einsteiger
Owner: Projekt-Owner bzw Unterstützer von Ihm - ist ja am ende ne Art Marketing :-)
Sprachen: Multi-Language?
Der erste große Teil der Webseite - ja wo leider noch seeeehr viel fehlt - ist die Übersicht über ioBroker (also "Was ist es) und dann die Haupt Themenbereiche. Die Seiten dort sollen speziell für Interessenten und Einsteigern zeigen wie cool ioBroker ist und was alles geht. Hier ist nicht das Ziel zu erklären wie alles geht, sondern erstmal das Projekt vorzustellen.
Mit dem Punkt "Tutorials" geht es dann in die ersten Schritte rein, wo man auch mal erste "Wie geht etwa" zeigt, aber Zielgruppe im ersten Schritt immer noch Einsteiger und Interessenten.
End-User-Support/Best-Practices
Zielgruppe: Nutzer (Einsteiger und höher)
Owner: ? (Community?)
Sprachen: Multi-Language?, ggf nur englisch?
Der zweite Teil der Webseite war die Idee die Nutzer zu entwickeln und typische Probleme zu vermeiden bzw auch Nutzern Best Practices an die Hand zu geben "Wie" man iobroker sinnvoll betreibt und nutzt. Nicht jeder muß alle Fehler machen :-)
Adapter-Dokumentation (End-User)
Zielgruppe: Adapternutzer (alle Level?)
Owner: Adapter-Entwickler/CommunityJeder Adapter-Entwickler kann neben einer minimalistischen README.md noch spezialisierte Seiten als Adapter-Dokumentation erzeugen. Das liegt bei jedem Entwickler und kann auch ggf aus der Community zugesteuert werden - da denke ich auch an die "Standardadapter" wie Admin/iot/Javascript ...
Für Adapter die auch erweitert zB durch Skripte genutzt werden können oder zB Bockly mitbringen kann auch dies sinnvoll sein ausführlicher zu Dokumentieren, ggf auch dann für "Skripter" als Zielgruppe.
Entwickler-Dokumentation (Generell)
Zielgruppe: Adapter-Entwickler
Owner: Devs?
Sprachen: von mir aus nur englisch
Dieser Dokumentationsteil sollte Überblick geben über "Wie entwickle ich einen Adapter?", aber auch Best Practices beleuchten und die Dokumentationen zentralisiert enthalten. Inhalt wäre noch zu füllen :-)
Aktuell ist hier vieles verstreut in JS-Controller Repo (Controller Feature-Overview), Repository (Best practices, Review Guidelines), ...
Entwicklungs-Unterstützende Doku/Tools
Zielgruppe: Adapter-Entwickler
Owner: Devs?
Sprachen: nur englischHier geht es neben Links und geschriebener Doku in die Bereiche wo wir schon erste Schritte getan haben:
- Types Defintion: Bringt mal mindestens für adapter.js und tools die Methoden-Signaturen mit wenn IDE es kann
- JSON-Schemas io-package/json-Config: unterstützt beim schreiben der JSONs wenn IDE es kann
- API-Docs: leider nur rudimentär und unvollständig in adapter.js ... fehlt noch
- Adapter-Creator: bringt viel mit und auch ein bissl Code
- ...
Ich bin sicher das ich noch Themen vergessen habe ... :-)
Was denkt Ihr dazu? Wie gehen wir das an?
Ingo F
bitte als wiki.
vielen ist markdown suspect bzw. haben/wollen auch kein github account -
bitte als wiki.
vielen ist markdown suspect bzw. haben/wollen auch kein github account -
Hi All,
ich weiss das die Kategorie nicht ganz passt, aber da heute in der Dev-Gruppe in Discord/Telegram eine Diskussion zum Thema "Dokumentation" aufgekommen ist, ist denke hier guter Startpunkt. Können wir ja noch verschieben.
In der Diskussion ist mir aufgefallen das wir mehrfach das "Thema" gewechselt haben. "Dokumentation" ist ein sehr großer Themenbereich und in meinen Augen gibt es hier verschiedene "Teilbereiche" die ggf auch andere Zielgruppen haben. Daher versuche ich hier einmal meine Sicht auf das große Thema zu geben und versuche es etwas zu strukturieren, wie ich es sehe. Damit wir uns dann in künftigen Diskussionen klar sind zu welchem "Teil" wir reden.
Als wir vor einiger Zeit die Dokumentation auf der Webseite (https://www.iobroker.net) neu gemacht haben steckt da durchaus ein Konzept dahinter. leider sind wir aktuell noch lange nicht damit fertig.
Hier genannte Themen kann man garantiert in sich auch nochmal kleiner brechen. Aber aus meiner Sicht ist eine Struktur bereits vorhanden - Sie muss "nur" noch mit Inhalt gefüllt werden
Generelle Projektdokumentation/-überblick
Zielgruppe: Interessenten, Einsteiger
Owner: Projekt-Owner bzw Unterstützer von Ihm - ist ja am ende ne Art Marketing :-)
Sprachen: Multi-Language?Der erste große Teil der Webseite - ja wo leider noch seeeehr viel fehlt - ist die Übersicht über ioBroker (also "Was ist es) und dann die Haupt Themenbereiche. Die Seiten dort sollen speziell für Interessenten und Einsteigern zeigen wie cool ioBroker ist und was alles geht. Hier ist nicht das Ziel zu erklären wie alles geht, sondern erstmal das Projekt vorzustellen.
Mit dem Punkt "Tutorials" geht es dann in die ersten Schritte rein, wo man auch mal erste "Wie geht etwa" zeigt, aber Zielgruppe im ersten Schritt immer noch Einsteiger und Interessenten.
End-User-Support/Best-Practices
Zielgruppe: Nutzer (Einsteiger und höher)
Owner: ? (Community?)
Sprachen: Multi-Language?, ggf nur englisch?Der zweite Teil der Webseite war die Idee die Nutzer zu entwickeln und typische Probleme zu vermeiden bzw auch Nutzern Best Practices an die Hand zu geben "Wie" man iobroker sinnvoll betreibt und nutzt. Nicht jeder muß alle Fehler machen :-)
Adapter-Dokumentation (End-User)
Zielgruppe: Adapternutzer (alle Level?)
Owner: Adapter-Entwickler/CommunityJeder Adapter-Entwickler kann neben einer minimalistischen README.md noch spezialisierte Seiten als Adapter-Dokumentation erzeugen. Das liegt bei jedem Entwickler und kann auch ggf aus der Community zugesteuert werden - da denke ich auch an die "Standardadapter" wie Admin/iot/Javascript ...
Für Adapter die auch erweitert zB durch Skripte genutzt werden können oder zB Bockly mitbringen kann auch dies sinnvoll sein ausführlicher zu Dokumentieren, ggf auch dann für "Skripter" als Zielgruppe.
Entwickler-Dokumentation (Generell)
Zielgruppe: Adapter-Entwickler
Owner: Devs?
Sprachen: von mir aus nur englischDieser Dokumentationsteil sollte Überblick geben über "Wie entwickle ich einen Adapter?", aber auch Best Practices beleuchten und die Dokumentationen zentralisiert enthalten. Inhalt wäre noch zu füllen :-)
Aktuell ist hier vieles verstreut in JS-Controller Repo (Controller Feature-Overview), Repository (Best practices, Review Guidelines), ...
Entwicklungs-Unterstützende Doku/Tools
Zielgruppe: Adapter-Entwickler
Owner: Devs?
Sprachen: nur englischHier geht es neben Links und geschriebener Doku in die Bereiche wo wir schon erste Schritte getan haben:
- Types Defintion: Bringt mal mindestens für adapter.js und tools die Methoden-Signaturen mit wenn IDE es kann
- JSON-Schemas io-package/json-Config: unterstützt beim schreiben der JSONs wenn IDE es kann
- API-Docs: leider nur rudimentär und unvollständig in adapter.js ... fehlt noch
- Adapter-Creator: bringt viel mit und auch ein bissl Code
- ...
Ich bin sicher das ich noch Themen vergessen habe ... :-)
Was denkt Ihr dazu? Wie gehen wir das an?
Ingo F
@apollon77 said in Strukturierungsversuch "Dokumentation":
Was denkt Ihr dazu?
Meine zwei Pfenige dazu aus vielen Jahren Entwicklung und Usersupport:
Ja, zum einen brauchen wir das Verständnis, welche Usergruppe welche Informationen in welcher Tiefe sucht (Entwickler, Anwender, Poweruser, ...).
Ich befürchte aber, dass die hilfreichen Infomationen nicht disjunkt sind. Das würde bedeuten, dass Dokumentation entweder mehrfach gepflegt werden müssen (blöd und meistens nie konsistent) oder dass man über eine passende Verknüpfung nachdenken sollte (Wiki grüßt schon einmal laut).Auch eine Suche (angefangen vom Inhaltsverzeichnis bis zum Stichwortverzeichnis) sollte berücksichtigen, dass nicht jeder nach definierten Begriffen und in (un-)bekannten Strukturen sucht (auch hier wieder ein Gruß von Wiki).
Mehrsprachigkeit: Das ist natürlich sinnvoll und hilfreich. Aufgrund des notwendigen Pflegeaufwands (jede minimale Änderung in der Quelle muss/sollte in x Sprachen übersetzt werden), wird nur eine automatische Übersetzung zielführend sein. Andernfalls schaut es aus wie Wiki(pedia): Ein Begriff, in jeder Sprache eine andere Info mit anderem Inhalt und Tiefe.
Wie gut das wirklich funktioniert, kann ich nicht beurteilen. Aber selbst sehr gute Werkzeuge wie Deepl (Deepl.com) haben sehr enge Grenzen (zumindest bei den Sprachen, wo ich mir ein kleines Urteil erlauben kann). -
@apollon77 said in Strukturierungsversuch "Dokumentation":
Was denkt Ihr dazu?
Meine zwei Pfenige dazu aus vielen Jahren Entwicklung und Usersupport:
Ja, zum einen brauchen wir das Verständnis, welche Usergruppe welche Informationen in welcher Tiefe sucht (Entwickler, Anwender, Poweruser, ...).
Ich befürchte aber, dass die hilfreichen Infomationen nicht disjunkt sind. Das würde bedeuten, dass Dokumentation entweder mehrfach gepflegt werden müssen (blöd und meistens nie konsistent) oder dass man über eine passende Verknüpfung nachdenken sollte (Wiki grüßt schon einmal laut).Auch eine Suche (angefangen vom Inhaltsverzeichnis bis zum Stichwortverzeichnis) sollte berücksichtigen, dass nicht jeder nach definierten Begriffen und in (un-)bekannten Strukturen sucht (auch hier wieder ein Gruß von Wiki).
Mehrsprachigkeit: Das ist natürlich sinnvoll und hilfreich. Aufgrund des notwendigen Pflegeaufwands (jede minimale Änderung in der Quelle muss/sollte in x Sprachen übersetzt werden), wird nur eine automatische Übersetzung zielführend sein. Andernfalls schaut es aus wie Wiki(pedia): Ein Begriff, in jeder Sprache eine andere Info mit anderem Inhalt und Tiefe.
Wie gut das wirklich funktioniert, kann ich nicht beurteilen. Aber selbst sehr gute Werkzeuge wie Deepl (Deepl.com) haben sehr enge Grenzen (zumindest bei den Sprachen, wo ich mir ein kleines Urteil erlauben kann). -
@apollon77 said in Strukturierungsversuch "Dokumentation":
Was denkt Ihr dazu?
Meine zwei Pfenige dazu aus vielen Jahren Entwicklung und Usersupport:
Ja, zum einen brauchen wir das Verständnis, welche Usergruppe welche Informationen in welcher Tiefe sucht (Entwickler, Anwender, Poweruser, ...).
Ich befürchte aber, dass die hilfreichen Infomationen nicht disjunkt sind. Das würde bedeuten, dass Dokumentation entweder mehrfach gepflegt werden müssen (blöd und meistens nie konsistent) oder dass man über eine passende Verknüpfung nachdenken sollte (Wiki grüßt schon einmal laut).Auch eine Suche (angefangen vom Inhaltsverzeichnis bis zum Stichwortverzeichnis) sollte berücksichtigen, dass nicht jeder nach definierten Begriffen und in (un-)bekannten Strukturen sucht (auch hier wieder ein Gruß von Wiki).
Mehrsprachigkeit: Das ist natürlich sinnvoll und hilfreich. Aufgrund des notwendigen Pflegeaufwands (jede minimale Änderung in der Quelle muss/sollte in x Sprachen übersetzt werden), wird nur eine automatische Übersetzung zielführend sein. Andernfalls schaut es aus wie Wiki(pedia): Ein Begriff, in jeder Sprache eine andere Info mit anderem Inhalt und Tiefe.
Wie gut das wirklich funktioniert, kann ich nicht beurteilen. Aber selbst sehr gute Werkzeuge wie Deepl (Deepl.com) haben sehr enge Grenzen (zumindest bei den Sprachen, wo ich mir ein kleines Urteil erlauben kann).@hans_999 hier geht es nur um eine Developer Doku.
Der Thread für die User Doku liegt woanders.
Die Userdoku hatces bereits in allen deinen Ausprägungen gegeben
GutHub Wiki
WordPress mehrsprachig
und jetzt basiert auf Markdown -
wie unterscheidest du den user zu developer?
sind developer nur die, die adapter und ähnliches bauen?
ist ein user, der ein skript mit blockly oder javascript baut ein user oder ein developer?ich denke das von, ich nenne es mal iobroker noop zu iobroker kenner, der übergang ein dynamischer/fließender prozess ist. manche habe schon programmierkenntnisse, evtl auch schon in javascript, manche überhaupt nix.
manche werden über das verwenden vorhandener adapter nicht hinaus kommen, andere wollen ihr smarthome superoptimieren und kriechen dann auch in die letzten technischen details
2 verschiedene dokus an verschiedenen orten zu machen ist nicht gut, da du dann schon automatisch eine Trennung nach Skills vornimmst.
Anfänger muss man bis zu einem bestimmten punkt anleiten. da sollte man durchgeleitet werden, bis ein definierter abschlusspunkt erreicht ist, um das erfolgserlebnis zu sichern.
evtl gibt es bei iobroker verschiedene themen nebeneinander, bei denen man zwischen Anfänger und Fortgeschrittene unterscheiden muss.- die Skripting-Ecke mit javascript/blockly/rules
- die Entwicklung von Adaptern/widgets
-
wie unterscheidest du den user zu developer?
sind developer nur die, die adapter und ähnliches bauen?
ist ein user, der ein skript mit blockly oder javascript baut ein user oder ein developer?ich denke das von, ich nenne es mal iobroker noop zu iobroker kenner, der übergang ein dynamischer/fließender prozess ist. manche habe schon programmierkenntnisse, evtl auch schon in javascript, manche überhaupt nix.
manche werden über das verwenden vorhandener adapter nicht hinaus kommen, andere wollen ihr smarthome superoptimieren und kriechen dann auch in die letzten technischen details
2 verschiedene dokus an verschiedenen orten zu machen ist nicht gut, da du dann schon automatisch eine Trennung nach Skills vornimmst.
Anfänger muss man bis zu einem bestimmten punkt anleiten. da sollte man durchgeleitet werden, bis ein definierter abschlusspunkt erreicht ist, um das erfolgserlebnis zu sichern.
evtl gibt es bei iobroker verschiedene themen nebeneinander, bei denen man zwischen Anfänger und Fortgeschrittene unterscheiden muss.- die Skripting-Ecke mit javascript/blockly/rules
- die Entwicklung von Adaptern/widgets
@oliverio sagte in Strukturierungsversuch "Dokumentation":
sind developer nur die, die adapter und ähnliches bauen?
ja!
Zumindest geht es hier nur um diesekein Support per PN! - Fragen im Forum stellen - es gibt fast nichts, was nicht auch für andere interessant ist.
Benutzt das Voting rechts unten im Beitrag wenn er euch geholfen hat.
der Installationsfixer: curl -fsL https://iobroker.net/fix.sh | bash -
-
@oliverio sagte in Strukturierungsversuch "Dokumentation":
sind developer nur die, die adapter und ähnliches bauen?
ja!
Zumindest geht es hier nur um diese@homoran
auf was ich hinaus wollte ist,
das aus user auch mal developer werden
und auch developer mal in den userbereich schauen müssen.
nicht alles ist trennscharf zwischen user und developer aufteilbar -
@homoran
auf was ich hinaus wollte ist,
das aus user auch mal developer werden
und auch developer mal in den userbereich schauen müssen.
nicht alles ist trennscharf zwischen user und developer aufteilbar@oliverio alles richtig!
da bin ich bei djr.
Aber dieser Thread (nicht die Doku) bezieht sich nur auf den Teil für Developer -
@OliverIO
gestern Nacht im Schlaf am Handy war es nicht so toll ;-)
also hier nochmals ausführlich.Ich stimme dir vollständig zu was den Inhalt der gesamten Doku angeht. Da muss es für jede "Entwicklungsstufe" eines Users eine entsprechende Info geben.
Dazu muss es eine verständliche Struktur in der Doku geben. Diese ist im Moment:
Auf der linken Seite.Hier in diesem Thread geht es aber nur um den Teil des linken Menüs für Adapterentwickler:
Alles andere bitte in dem Parallelthread:
https://forum.iobroker.net/topic/49319/strukturierungsversuch-doku-allgemein?_=1636883572033
Support us
851
Online32.4k
Users81.5k
Topics1.3m
Posts