Strukturierungsversuch "Dokumentation"

[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