Strukturierungsversuch "Dokumentation"

[apollon77]

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/Community

Jeder 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 englisch

Hier 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

[Jey Cee]

@apollon77 die Struktur war für mich nie ein Thema, die passt. Und ich denke das sehen viele so.
Das einzige was ich ändern würde ist der Punkt Visualisierungen, das gehört zu den Adaptern und die haben sogar eine eigene Unterseite auf der Seite. An dieser Stelle muss dann ein Link auf diese Unterseite zu finden sein, es ist nicht ersichtlich wo man die Doku zu den Adaptern findet.

In meinen Augen sollte der ganze Content erstmal raus, da sind zu viele Platzhalter drin. Die Automatische Übersetzung muss deaktiviert werden, die hat mehr Probleme verursacht als was es genutzt hat.
Entwickler Doku nur noch in Englisch und im Deutschen ein Link darauf, das hatten wir schon mal besprochen!

Soweit ich mich erinnern kann war immer unklar wann Änderungen auf der Webseite auftauchen, es muss irgendwie für die Mitwirkenden deutlich werden wann das passiert.

[apollon77]

Das einzige was ich ändern würde ist der Punkt Visualisierungen, das gehört zu den Adaptern und die haben sogar eine eigene Unterseite auf der Seite. An dieser Stelle muss dann ein Link auf diese Unterseite zu finden sein,

Das haben wir Absichtlich so und gehört zum "Projektmarketing". Für viele Interessenten geht es auch darum wie es am Ende für die Bedienung aussehen kann bzw welche Apps es gibt. Daher ist das dort prominent wichtig. Ziel ist dort nur die "schau mal wie Cool" zu haben ... Details und "Wie" und so kommt dann in die Tutorials oder in die Adapter-Doku.

es ist nicht ersichtlich wo man die Doku zu den Adaptern findet.

Gute Frage .. früher gabs das mal als Punkt auch in der Haupt-Navi ... jetzt ists nur oben in der Top Navi.

In meinen Augen sollte der ganze Content erstmal raus, da sind zu viele Platzhalter drin. Die Automatische Übersetzung muss deaktiviert werden, die hat mehr Probleme verursacht als was es genutzt hat.
Entwickler Doku nur noch in Englisch und im Deutschen ein Link darauf, das hatten wir schon mal besprochen!

Da ist in jedem Fall was wahres dran. muss man mal überlegen wie man es am besten macht. Das wären dasnn ggf 3 Issues im Doku Projekt, weil es sonst keine Sichtbarkeit bekommt

Soweit ich mich erinnern kann war immer unklar wann Änderungen auf der Webseite auftauchen, es muss irgendwie für die Mitwirkenden deutlich werden wann das passiert.

Alle 3 Tage wird die iobroker.net neu gebaut ... Das wäre aktuell die maximale Wartezeit.

[paul53]

@jey-cee sagte: Die Automatische Übersetzung muss deaktiviert werden, die hat mehr Probleme verursacht als was es genutzt hat.

Stimmt! Ich hatte mal Rolle von Datenpunkten korrigiert und nun steht wieder eine Menge "Müll" drin.

[OliverIO]

@paul53 sagte in Strukturierungsversuch "Dokumentation":

@jey-cee sagte: Die Automatische Übersetzung muss deaktiviert werden, die hat mehr Probleme verursacht als was es genutzt hat.

Stimmt! Ich hatte mal Rolle von Datenpunkten korrigiert und nun steht wieder eine Menge "Müll" drin.

bzw ein flag, bei dem man markieren kann was nicht übersetzt werden darf.
wenn englisch definierte datenpunkte automatisch in der doku übersetzt werden dann ist das müll. und so hab ich noch ein paar beispiele in meinen adaptern.

[Homoran]

@oliverio sagte in Strukturierungsversuch "Dokumentation":

dann ist das müll

dann wird das durch die Wache gemeldet

[apollon77]

@oliverio Ja sowas gabs... habe deswegen im altuellen PR von @paul53 gefragt

[OliverIO]

@apollon77

bitte als wiki.
vielen ist markdown suspect bzw. haben/wollen auch kein github account

[apollon77]

@oliverio Nope, diese Diskussion hatten wir und ehrlich: MD is "the way to go". Alles andere ist outdated. Sorry

[hans_999]

@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).

[paul53]

@hans_999 sagte: wird nur eine automatische Übersetzung zielführend sein.

Das ist sie nicht, weil es erhebliche Teile gibt, die nicht übersetzt werden dürfen. Das leistet keine automatische Übersetzung.

[Homoran]

@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

[OliverIO]

@homoran

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

[Homoran]

@oliverio sagte in Strukturierungsversuch "Dokumentation":

sind developer nur die, die adapter und ähnliches bauen?

ja!
Zumindest geht es hier nur um diese

[OliverIO]

@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]

@oliverio alles richtig!
da bin ich bei djr.
Aber dieser Thread (nicht die Doku) bezieht sich nur auf den Teil für Developer

[Homoran]

@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