Diskussion zur Strukturierung einer Doku-Seite

[crunchip]

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Wenn du dir schon die Arbeit machst etwas Allgemeingültiges zu schreiben, was spricht dann dagegen es genau an der Stelle zu Platzieren wo es ohnehin stehen sollte?
Davon haben dann alle mehr und der nächste der die Seite Anfasst fängt nicht bei 0 an.

Wie soll das bitte funktionieren?, Ich beginne mit einem Thema, in diesem wird Xyz angesprochen, jetzt muss ich erst mal xyz schreiben, damit ich mit meinem eigentlich weitermachen/verlinken kann. Und so zieht sich das duch mehrere Themen und nimmt kein Ende.
Letzendlich, habe ich aus gegebenen Anlass, weil einiges schon ausführlichst im Forum dazu nieder geschrieben wude, bewusst darauf verlinkt.

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

aber deswegen kannst du die Seite doch um deinen Text ergänzen.

könnte ich, hab aber keine Vorstellung wie, soll ichs einfach unten dran klatschen, oder sollte es zielgerecht eingebaut werden, was wiederum sehr viel zeit in Anspruch nimmt, da fehlt mir das Verständnis wie das funktionieren soll, wenn dann plötzlich jemand sich der Seite annimmt und selbst eine Beschreibung erstellt.

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Naja man sollte schon Quellen wählen die Sinn machen. Und ich verstehe auch das man alles möglichst genau Erklären möchte, aber deswegen muss man nicht bei Adam & Eva anfangen oder das Rad neu erfinden.
Daher denke ich solange es mit entsprechenden Quellen Unterlegt ist, kann eine Erklärung sich auf den ioBroker Spezifischen Teil beschränken.

bin ich einfach anderer Meinung, wenn man mit der Materie noch nie etwas am Hut hatte, sind diese besagten Seiten dann ebenfalls nicht zielführend.

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Gut, aber in dem Github Entwurf von dir verweist du ja selbst auf die Installtionsanleitung von Node.JS. Warum?

damit man sieht woher es kommt

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Es erscheint mir nicht besonders Sinnvoll schon am Anfang alle Möglichen Probleme auf zu Zählen

wenn die installation schon im Vorfeld verbogen ist, nützt mir im Nachgang eine Problemlösung auch nur bedingt und hätte mir die dadurch entstehenden Probleme erspart

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Sondern eine andere Art von Struktur zu Zeigen.

habe ich wahr genommen

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Wir brauchen beides, entweder in einem oder getrennt. Für mich macht es Sinn beides zusammen zu haben.
Spart Arbeit und erleichtert es wenn man doch schnell mal was nach lesen muss.

da sind wir einer Meinung, und ich habe es nun mal in meinem Entwurf, direkt zusammen gepackt.

[Jey Cee]

@homoran jetzt mach mal halb Lang, du wirfst mir vor das ich zu Faul bin mir Hintergrund wissen an zu eignen.
Dann willst du aber jedem von Anfang erklären wie er zu einem Funktionierenden ioBroker inkl. allem drum und dran kommt. Servierst es dem User also auf dem Silbertablett.

Was jetzt, soll man sich nun selber was aneignen oder vielleicht doch nicht?

Es gehört nun mal dazu ein gewisses Hintergrund wissen mit zu bringen oder es sich eben zu holen. Diesem Anspruch wird meine Art der Doku gerecht, den es wird jedem die Möglichkeit gegeben sich das Wissen an zu lesen. Man muss im ersten Schritt noch nicht mal eine Suche benutzen, dank Links.
Und genau damit ist eine der größten Hürden bereits genommen an der es eben oft scheitert.

@homoran sagte in Diskussion zur Strukturierung einer Doku-Seite:

Hast du mal ernsthaft versucht es mit den Augen eines hilfesuchenden Einsteigers zu sehen?

Klar bin ich doch oft genug selber, nicht mehr bei ioBroker, aber bei anderen Dingen.

[Homoran]

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

du wirfst mir vor das ich zu Faul bin mir Hintergrund wissen an zu eignen.

Nein! Das hast du falsch verstanden. Lies es nochmaal

[crunchip]

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Dann willst du aber jedem von Anfang erklären wie er zu einem Funktionierenden ioBroker inkl. allem drum und dran kommt

die Grundkenntnisse und Fehlerquellen sollten einem Neueinsteiger ausführlichst dargestellt werden.

wenn dieser mit der Zeit sich ein wenig mit iobroker auseinander gesetzt hatt, fällt es ihm auch leichter und versteht Erweiterte Beschreibungen, dann besser.

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Es gehört nun mal dazu ein gewisses Hintergrund wissen mit zu bringen oder es sich eben zu holen

und das möchte man dem User doch aufzeigen, denn es setzt nicht gewisse Grundkenntnisse vorraus, falsche Denkweise

als ich einst auf iobroker stieß, war das durch Zufall, als ich eins dieser "kein Schimmer Video`s" gesehen hatte

mit Linux jedoch noch nie in Kontakt gewesen.

[Jey Cee]

@crunchip sagte in Diskussion zur Strukturierung einer Doku-Seite:

da fehlt mir das Verständnis wie das funktionieren soll, wenn dann plötzlich jemand sich der Seite annimmt und selbst eine Beschreibung erstellt.

Das wird dir aber auch kaum jemand anderes vermitteln können. Bisher gibt es nämlich nichts ausformuliertes dazu.
Wer zu erst kommt, mahlt zuerst.
Die einzige Richtlinie die ich hier sehe, einfach nichts löschen von dem du dir nicht sicher bist das es weg kann.
Dank Github wäre es aber auch dann nicht Endgültig verloren.

@crunchip sagte in Diskussion zur Strukturierung einer Doku-Seite:

Wie soll das bitte funktionieren? Ich beginne mit einem Thema, in diesem wird Xyz angesprochen, jetzt muss ich erst mal xyz schreiben,

Hä? Also entweder XYZ existiert oder du musst es schreiben, soweit logisch. Aber wenn du es doch schon geschrieben hast, weil du es in deiner Anleitung verwendest, stellt sich doch die Frage nicht mehr.
Es geht doch nur um Inhalte die du ohnehin geschrieben hast im Zuge der Doku die du gerade erstellst.

@crunchip sagte in Diskussion zur Strukturierung einer Doku-Seite:

damit man sieht woher es kommt

Dann ist jetzt genau das passiert was ich als Kritikpunkt habe, ich hab die Befehle in deinem Text Übersehen.

[Jey Cee]

@homoran sagte in Diskussion zur Strukturierung einer Doku-Seite:

Nein! Das hast du falsch verstanden. Lies es nochmaal

@homoran sagte in Diskussion zur Strukturierung einer Doku-Seite:

Keinen Hintergrund, keine verständnisfördernden Sachen - alles zu wuchtig. Ist dir alles zu anstrengend.

Vielleicht solltest du es nochmal lesen!

[Homoran]

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Vielleicht solltest du es nochmal lesen!

ich wiederhole mich:
Das hast du falsch verstanden.

Das waren deine Aussagen, was du in einer Doku nicht haben möchtest, weil es für dich zu anstregend sei, das zu lesen.

@homoran sagte in Diskussion zur Strukturierung einer Doku-Seite:

Du willst nur kurz nachschlagen, ... Keinen Hintergrund, keine verständnisfördernden Sachen - alles zu wuchtig.
Ist dir alles zu anstrengend.

[crunchip]

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Wer zu erst kommt, mahlt zuerst.

Bis dato standen Die Mühlräder eher still.

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Bisher gibt es nämlich nichts ausformuliertes dazu.

Zumindest ja jetzt die Arbeitsgruppen

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Hä? Also entweder XYZ existiert oder du musst es schreiben, soweit logisch

Verstehst du was ich geschrieben habe?
Ich beschreibe ein Thema, darin verlinke ich zu einem Part in der Doku, der noch nicht vorhanden ist.
Selber schreiben is nicht, da ich z.b

• von dem Part keine Ahnung habe
• zu komplex ist was das drei oder vierfache an Zeit in Anspruch nimmt,
• in diesem Part wiederum Verlinkungen enstehen, die das selbe Auslösen und das zu einer Endlosschleife wird.

@jey-cee sagte in Diskussion zur Strukturierung einer Doku-Seite:

Dann ist jetzt genau das passiert was ich als Kritikpunkt habe, ich hab die Befehle in deinem Text Übersehen.

Über Struktur lässt sich reden, ich versuche die Tage mal, es etwas anders aufzubauen

Im übrigen steht der Installationbefehl doch klar und deutlich sichtbar im Absatz Akualisierung.
Ungünstig positioniert ist macos und Windows, weil ich das im nachhinein platziert hatte.
Das muss besser aufgeteilt werden

[OliverIO]

@jey-cee
So ich auch noch.

Also grundsätzlich würde ich die Doku eher für den Einsteiger sehen.
Fortgeschrittene haben schon eher die Fähigkeiten sich die Informationen da herauszulesen, im Forum zu schauen oder sich das Wissen selbst zu erarbeiten.
Viele Anfänger hier sind ja nicht nur im Thema iobroker neu, sondern auch wie betriebe ich einen Server oder gar neu mit Linux. Viele Begriffe, Befehle die im Forum so rumschwirren sind böhmische Dörfer. man hat überhaupt gar keine Ahnung was es bedeutet, viele haben eine zu kurze Aufmerksamkeitsspanne oder einfach zu wenig Zeit und Lust sich ausführlichts im Internet über alle Befehle vorzuinformieren, also wird einfach abgetippt was man irgendwo sieht und einigermaßen in die Problemstellung passt. Natürlich verstehen die meisten den genauen Kontext, warum der Befehl hier gerade eingetippt werden muss nicht.

Daher denke ich, das man schon ein wenig mehr schreiben bzw. woanders hin verlinken muss.

@Jey-Cee Das Beispiel find ich ebenfalls gut, aber ist halt nur sehr knapp beschrieben und hilft den Fortgeschrittenen sicherlich als Merkzettel, was der Reihe nach abgearbeitet werden muss um ein Ziel zu erreichen.
Die Trennung von Text und Befehl finde ich allerdings nicht so gut, da man als Anfänger dann dauernd hin und her klickt und ggfs. auch mal einen Schritt überspringt.

Wie wäre es mit einer Trennung in der Gliederung, so das die für Fortgeschrittenen relevanten Elemente schnell erkennbar sind und der Rest überlesen werden kann?
Wenn man so eine Gliederung standardisiert, so kann jeder sein Teil an Information leichter finden.

Überschrift/Abschnitt/Schritt x

Beschreibung

<Hier der ausführlichere Text mit Links und ggfs. Bildern>

Befehle

iob fix

[Muchul]

Die Befehle im Text finde ich gut, weil dann das Verständnis dafür auch vermittelt wird.
Allerdings könnte am Anfang erwähnt werden dass der Text erst gelesen werden sollte, für Anfänger und unten die Befehle nochmal untereinander stehen.
Wäre doch beiden Zielgruppen geholfen, oder nicht?

[crunchip]

@oliverio sagte in Diskussion zur Strukturierung einer Doku-Seite:

oder gar neu mit Linux. Viele Begriffe, Befehle die im Forum so rumschwirren sind böhmische Dörfer. man hat überhaupt gar keine Ahnung was es bedeutet

richtig,
ein Beispiel
der User schildert sein Problem,
man antwortet, zeig mal die Ausgabe von

iob update -i
apt policy nodejs

als Antwort erhält man die Ausgabe, mit dem Text, Fehler besteht weiterhin
es gibt soviele User die hier um Rat fragen, man geht das Problem mit ihm durch, letztendlich aber gar keinen Plan haben, was sie da eigentlich abtippen, bzw was diese Befehle bewirken/bedeuten.

Man kann nicht erwarten, das man sich vorher komplett einliest in sämtlichen Themenbereiche, die Zielgruppen sind total unterschiedlich, vereinfacht ausgedrückt
der eine möchte etwas steuern, "bisschen Smarthome", der andere etwas auslesen, Statistiken..(Strom,Heizung),
User A sucht bewusst nach einer Möglichkeit dies zu tun, User B kommt durch Zufall auf iobroker.
Schnell installiert(stellt sich das leichter vor als gedacht), und nun erkennt er erst, was da alles dran hängt, was da alles zu tun ist, mit was man sich alles auseinander setzen muss und denkt sich...ich wollte doch eigentlich nur...
doch da ist er schon mittendrin und letzendlich hilflos

anderes Beispiel
Probleme bei der Installation einer InfluxDb, klar man kann auf die offizelle Seite verweisen, ein Linuxfremder tut sich da allerdings sehr schwer,
zum einen, weil er die Bedeutung der Befehle nicht kennt, nicht versteht, was er da eingeben muss, das mancher Befehl noch angepasst werden muss, oder gar die Info fehlt, dass das ein oder andere Packet noch nachinstalliert werden muss