Strukturierungsversuch Doku - Allgemein

[Feuersturm]

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

[Homoran]

@feuersturm oder so!
Wobei nicht jeder User ein Freund von GitHub ist

[crunchip]

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

[OliverIO]

@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

[Homoran]

@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

[paul53]

@oliverio sagte: das dokumentation auch bestandteil der entwicklung ist

Das sollte sie sein, wird aber von Programmierern gern vernachlässigt.

[Homoran]

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

[Feuersturm]

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

Ich 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.

[crunchip]

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

[Homoran]

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

Auß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.

[Segway]

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 ?

[Jey Cee]

@segway suche und oder Filter auf der Seite benutzt?
https://www.iobroker.net/#de/documentation/config/cli.md

[Segway]

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

[Homoran]

@segway
bei mir klappt es

aber das passiert, wenn content angelegt wird zu dem es keine Struktur gibt.
Da hätte auch die Struktur angelegt werden müssen.

[Jey Cee]

@segway ok der Suchbegriff liefert viel zu viele Ergebnisse, aber den Filter im Menü hast du nicht verwendet den der Liefert das gesuchte.

[Segway]

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

[Feuersturm]

@homoran Aber auch nur, wenn man den genauen Begriff eingbit. Wenn man nur "Konsole" eingibt, kommt eine erste Auswahl und unten "More 15 results ...". Klickt man hier drauf kommt man auf eine leere Seite

Auch wenn man den exakten Begriff eingibt, öffnet sich links der Baum nicht, so dass man nicht weiß, wo die Seite liegt

[Homoran]

@feuersturm sagte in Strukturierungsversuch Doku - Allgemein:

Auch wenn man den exakten Begriff eingibt, öffnet sich links der Baum nicht, so dass man nicht weiß, wo die Seite liegt

das habe ich gerade auch gesehen, liegt aber IMHO daran

@homoran sagte in Strukturierungsversuch Doku - Allgemein:

wenn content angelegt wird zu dem es keine Struktur gibt.
Da hätte auch die Struktur angelegt werden müssen.

[Segway]

@feuersturm sagte in Strukturierungsversuch Doku - Allgemein:

@homoran Aber auch nur, wenn man den genauen Begriff eingbit. Wenn man nur "Konsole" eingibt, kommt eine erste Auswahl und unten "More 15 results ...". Klickt man hier drauf kommt man auf eine leere Seite

Yep kann ich bestätigen !

[Jey Cee]

@homoran sagte in Strukturierungsversuch Doku - Allgemein:

das habe ich gerade auch gesehen, liegt aber IMHO daran
@homoran sagte in Strukturierungsversuch Doku - Allgemein:

wenn content angelegt wird zu dem es keine Struktur gibt.
Da hätte auch die Struktur angelegt werden müssen.

Meinst du etwa diese Struktur?