Strukturierungsversuch "Dokumentation"
-
@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.
-
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.
-
@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.
-
@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. -
@oliverio sagte in Strukturierungsversuch "Dokumentation":
dann ist das müll
dann wird das durch die Wache gemeldet
-
-
bitte als wiki.
vielen ist markdown suspect bzw. haben/wollen auch kein github account -
@oliverio Nope, diese Diskussion hatten wir und ehrlich: MD is "the way to go". Alles andere ist outdated. Sorry
-
@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 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.
-
@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
-
@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 -
@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
