Diskussion zur Strukturierung einer Doku-Seite
-
MOD-EDIT:
Dieser Thread wurde aus dem Thread https://forum.iobroker.net/topic/51756/doku-node-js-update ausgegliedert, da es sich hier um eine allgemeine Diskussion handelt und nicht nur für die nodejs Seite zutrifft
@crunchip ich hab drüber gesehen, also geöffnet und mehr oder weniger gleich wieder geschlossen.
Genau so eine Art von Doku oder auch Blog schau ich mittlerweile nur noch an wenn ich nichts anderes Finde.
Warum? Das lässt sich vielleicht am besten mit einer einfachen Frage beantworten:
Ist das eine Erklärung oder eine Anleitung?Ich finde es anstregend in einem so Wuchtigen Text nach einer Anleitung zu suchen. Das mag für den einstieg nötig sein, aber um nur schnell die Befehle bzw. die Vorgehensweise zur Hand zu haben wenn man weis was man tut, ist es unpraktisch.
Erklärung und Anleitung auf einer Seite zu haben macht auf jeden Fall Sinn, aber so getrennt das man schnell die Anleitung hat und bei bedarf auch eine weiter gehende Erklärung.Das bezieht sich jetzt nicht nur auf das was du erstellt hast, auch andere Seiten der Doku sind so.
Nur beim drauf schauen auf deine ist es mir eben so klar geworden das ich es in Worte fassen konnte.Ein Sinnvoller Aufbau könnte sein das zuerst die Einleitung kommt, dann der Ablauf mit Erklärung und am Ende die Anleitung.
-
@jey-cee sagte in Doku node.js Update:
Genau so eine Art von Doku oder auch Blog schau ich mittlerweile nur noch an wenn ich nichts anderes Finde.
das ist aber genau das Problem!
die jetzt immer verstärkt auftretenden technischen Dokus 'made by developer' sind keinem Einsteiger zuzumuten.
Noch schlimmer ist, dass bestehende gute Dokus damit überschreieben werden/worden sind.Natürlich muss eine Struktur vorhanden sein.
Aber hier sind wir nicht bei einer Adapterreferenz!
Und leider trifft da das von mir gesagte erst recht zu - traurig!und ja!
@jey-cee sagte in Doku node.js Update:
Das mag für den einstieg nötig sein, aber um nur schnell die Befehle bzw. die Vorgehensweise zur Hand zu haben wenn man weis was man tut, ist es unpraktisch.
und genau für die User die nicht wissen was sie tun, es aber verstehen wollen ist ide Doku
-
@oliverio danke,
das es Inhaltlich im Unteren Teil noch etwas durcheinander ist, kam, weil ich den windows Part im nachhinein gepackt habe.Wenn es aber zum Teil bereits schon hervorragende Anleitungen im Forum gibt, sollte das auch an dieser Stelle verlinkt werden. Andernfalls sprengt das den Rahmen der Seite.
Oder man bezieht sich nur aufs wesentliche und wirft dennoch wieder Fragen auf.Es war ein erster Versuch, aber wie bekannt, fehlt mir die Erfahrung, sei es dem Thema bezüglich und zum anderen der Umgang mit Github/Markdown.
@jey-cee sagte in Doku node.js Update:
Ist das eine Erklärung oder eine Anleitung?
Für mich beides, weil
- Eines zum anderen gehört
- Ich aktuell keinen Platz in der Doku Aufgliederung sehe, wo was genau hingehört.
Andernfalls trennt man das in drei Kategorien
- Was ist nodejs
- Update( Bei Erstinstallation ist nodejs ja auch schon ein Thema
- Fehlerbeschreibung
@jey-cee sagte in Doku node.js Update:
Ich finde es anstregend in einem so Wuchtigen Text
Oder ich lasse es doch so zusammen auf einer Seite, jedoch mit aufklappbarem Menü damit es übersichtlicher wird.
-
@crunchip sagte in Doku node.js Update:
Es war ein erster Versuch, aber wie bekannt, fehlt mir die Erfahrung, sei es dem Thema bezüglich und zum anderen der Umgang mit Github/Markdown.
Nicht falsch verstehen. du wolltest das man drüber schaut. Besser ist wenn mehrere drüber schauen, damit verschiedene Eindrücke entstehen.
ich find die Doku gut. Nicht von anderen verunsichern lassen. Erst mal ein Gegenbeispiel zeigen lassen.Solange das nicht passiert ist, ist die Doku die existiert besser als etwas was viel besser aussehen könnte, aber nicht da ist.
-
@homoran sagte in Doku node.js Update:
die jetzt immer verstärkt auftretenden technischen Dokus 'made by developer' sind keinem Einsteiger zuzumuten.
Also den Punkt versteh ich jetzt im Bezug auf das was ich geschrieben habe gar nicht.
Den Aufbau den ich Vorgeschlagen habe findest du in Fachbüchern (egal welches Fach), Wikipedia und sogar Fachliche Zeitungsartikel sind so aufgebaut. Das ist bewährt und wird sogar heute noch so in Schulen Praktiziert.- Einleitung / Erklärung um an das Thema heran zu führen
- Theoretischer Teil
- Praktischer Teil
@homoran sagte in Doku node.js Update:
und genau für die User die nicht wissen was sie tun, es aber verstehen wollen ist die Doku
Falsch: Die Doku ist auch für die die schon drin stecken, aber an Allzheimer leiden und sich nicht (mehr) den ganzen Brockhaus Band Auswendig merken können.
Darüber hinaus ändert sich im Bereich Software auch mal der ein oder andere Befehl, wenn nicht sogar der Ablauf. Deswegen schau ich fast immer in die offiziellen Dokus, um sicher zu gehen das ich dem Aktuell vorgeschlagenen weg folge.Bestes Beispiel ist die Installation von ioBroker.
Früher war das eine relativ Aufwendige Angelegenheit, heute ist es nur noch ein Befehl inkl. Nodejs.
Und trotzdem installieren viele User noch immer Nodejs von Hand, weil das überall so steht. Selbst erfahrene Benutzer machen das noch so und verweisen auf die Doku. -
@oliverio dem kann ich nur zustimmen!
Ich finde diese Doku auch gut.@crunchip sagte in Doku node.js Update:
fehlt mir die Erfahrung,
Ist genau richtig was du machst: versuchen aus der Sicht eines Einsteigers zu sehen was er braucht zum arbeiten und braucht zu verstehen, warum er das so machen soll.
@crunchip sagte in Doku node.js Update:
Ich aktuell keinen Platz in der Doku Aufgliederung sehe, wo was genau hingehört.
ich habe vorhin noch einmal die Menütitel aktualisiert, nachdem es beim letzten mal anscheinend zu einem Unfall gekommen war und ein älterer pullrequest danach gemerged wurde, was meine Änderungen wieder überschrieben hat.
Wenn ich das richtig sehe, steht der Artikel in der Rubrik Updates
"Software update": { "title": { "en": "Software update", "de": "Softwareupdate", "ru": "Обновление", "zh-cn": "系统更新" }, "pages": { "General": { "title": { "en": "General", "de": "Allgemein", "ru": "установка", "zh-cn": "安装" }, "content": "install/update.md" }, "ioBroker": { "title": { "en": "ioBroker", "de": "ioBroker", "ru": "установка", "zh-cn": "安装" }, "content": "install/updateself.md" }, "Adapter": { "title": { "en": "Adapter", "de": "Update eines Adapters", "ru": "Обновить адаптер", "zh-cn": "更新适配器" }, "content": "install/updateadapter.md" }, "Node.js & npm": { "title": { "en": "Node.js & npm", "de": "Update NodeJS", "ru": "Обновить NodeJS", "zh-cn": "更新NodeJS" }, "content": "install/updatenode.md" } } } } },und dafür ist der Text genau richtig
-
@jey-cee sagte in Doku node.js Update:
Also den Punkt versteh ich jetzt im Bezug auf das was ich geschrieben habe gar nicht.
dann lies ihn nochmal, vielleicht verstehst du es dann.
in etwa:
Du willst nur kurz nachschlagen, am besten nur nach den Befehlen.
Keinen Hintergrund, keine verständnisfördernden Sachen - alles zu wuchtig. Ist dir alles zu anstrengend.Und genauso sehen inzwischen viele Dokus im Adapterbereich aus, weil in den alten Anleitungen zu viele anstrengende Screenshots waren, und dann auch noch jeder Punkt in der Konfiguration erklärt wurde.
Das war einfach zu wuchtigam besten eine zweiseitige Anleitung ersetzen durch so was:
https://www.iobroker.net/#de/adapters/adapterref/iobroker.history/README.mdvorher sah es in etwa so aus:
https://www.iobroker.net/docu/index-191.htm?page_id=144&lang=de
(hier fehlen nur inzwischen die Screenshots) -
damit demotivierst du diejenigen, die überhaupt etwas machen wollen und verhinderst das überhaupt etwas da ist oder entsteht.
Ich finde es gut, wie @crunchip es gemacht hat und ich habe schon viele Dokumentationen und Spezifikationen geschrieben.
Außerdem setzt du die Latte dann schon sehr hoch und willst sofort perfekte Anleitungen/Artikel?
Wir können ja einen Wettbewerb machen. Du erstellst genau die gleiche Seite nach deinen Vorstellungen und lässt die Community abstimmen.
Evtl kann man dadurch Standards für die nächsten Artikel herausfinden bzw. verbessern. -
@oliverio sagte in Doku node.js Update:
Nicht falsch verstehen. du wolltest das man drüber schaut. Besser ist wenn mehrere drüber schauen, damit verschiedene Eindrücke entstehen.
Richtig, fasse ich auch nicht falsch auf, bin für jeden Tipp dankbar.
@oliverio sagte in Doku node.js Update:
damit demotivierst du diejenigen, die überhaupt etwas machen wollen und verhinderst das überhaupt etwas da ist oder entsteht.
Nicht sofort aber auf dauer ja,
das "Ding" ich nenne es mal so, steht mehr oder weniger seit über nem Jahr leer.
Ich weiss gar nicht wie oft ich das aufgeschlagen habe und mir die einzelnen Rubriken angesehen habe. Jedoch keinen Ansatz finden konnte, was wie wo hin soll.Ich hatte auch den Vorschlag unterbreitet, es aufzuteilen, Einsteiger, Fortgeschritten, genauso wie ich der Meinung bin, was am gewichtigsten, schnellstens in die Doku muss, wenn man die vielen Foreneinträge betrachtet.
Es wurde schon sehr viel darüber geschrieben, man sollte, man könnte,...
Aber es passiert nichts.Und nun freut es mich umso mehr, das plötzlich es den ein oder anderen gepackt hat, aktiv mitzuwirken und wenn das so bleibt, auch schnellsten ne vernünftige Doku zu stande kommt.
Perfektion mal aussen vor, den Feinschliff kann man immer noch anpassen, aber zumindest sind die Inhalte dann brauchbar gefüllt. -
@oliverio sagte in Doku node.js Update:
damit demotivierst du diejenigen, die überhaupt etwas machen wollen und verhinderst das überhaupt etwas da ist oder entsteht.
Das ist absolut nicht meine Absicht, aber es wurde nach Feedback gefragt.
Und das sind eben Kriterien nach denen ich eine Dokumentation bewerte, als Entwickler und Benutzer. Dabei spielt es für mich keine Rolle ob es um Software geht oder ein Kochrezept.Ich hab damit auch nicht die Inhaltliche Qualität dessen was @crunchip erstellt hat Bewertet, dazu hätte ich es ganz lesen müssen und das hab ich nicht.
Was ich bewertet habe war der Aufbau und der entspricht einfach nicht dem was ich erwarte.So viel Meinung sollte man ertragen.
-
@jey-cee sagte in Doku node.js Update:
Und das sind eben Kriterien nach denen ich eine Dokumentation bewerte
Stehen die Kriterien irgendwo dokumentiert, nach denen man sich richten sollte?
@jey-cee sagte in Doku node.js Update:
hätte ich es ganz lesen müssen
Eben, dann demotivieren solche Sätze
@jey-cee sagte in Doku node.js Update:
ich hab drüber gesehen, also geöffnet und mehr oder weniger gleich wieder geschlossen.
Umso mehr
Aber unabhängig davon, werde ich mir die Vorschläge nochmal durch den Kopf gehen lassen und sehen wie ich es besser machen kann.
-
Hey All,
Hey @crunchip,ich finde es super das DU dir das Thema annimmst.
Jeder Content den wir dazu bekommen können ist super.
Wie man es am besten für alle Zielgruppen strukturiert ist denke etwas was wir lernen müssen. In dem Fall hier ist vllt eine Anleitung mit nur den Befehlen schwierig weil dann auch die User die nicht wissen was Sie tun zum vermeintlich kurzen/schnellen greifen "ohne zu wissen was Sie da tun"
Ich denke auch das wir lernen werden wie was ankommt und können nachbessern.Das Du hier um Feedback fragst ist super und ja dann kommt halt auch Feedback
Am Ende würde ich es aber erstmal so sehen wie bei der Adapter-Entwicklung auch: Im ersten Schritt gewinnt der der sich die Arbeit macht (unter der Premisse natürlich das es generell sinnvoll ist was im Text steht ) Der Verfasser entscheidet welches Feedback er wie verarbeitet. Keiner sollte sich durch Feedback angegriffen fühlen.Und ich persönlich würde es aktuell eher pragmatisch sehen: Jeder (sinnvolle und zur Struktur/Idee passende) Content ist besser als keiner. Optimieren, Kürzen, Verteilen, Verschieben u.ä. können wir immer noch in einem zweiten Schritt. Wir können hier iterative arbeiten und sollten es auch ...
Ingo
-
@apollon77 sagte in Doku node.js Update:
Das Du hier um Feedback fragst ist super und ja dann kommt halt auch Feedback
da spricht nichts dagegen, die Art und Weise ist entscheidend. Statt "herab lassend" zu kritisieren, wäre es wünschenswert, wenn ein "alter Hase" dem "Neuling" konstruktiv und unterstützend unter die Arme greift.
Gerade bezüglich auf den screen unten, Redis Datenbank, dachte ich mach dir einen gefallen, hab deine Infos aus dem Forum und den Rest aus dem Internet zusammen geklaubt, du hast mir noch Tpps gegeben dass das ein oder ander noch mit aufgenommen werden sollte, hast den ein oder anderen Satz noch etwas umformuliert und fertig war der Lack, zack und eine Seite mehr in der Doku, ohne gross Tam Tam
@apollon77 sagte in Doku node.js Update:
In dem Fall hier ist vllt eine Anleitung mit nur den Befehlen schwierig weil dann auch die User die nicht wissen was Sie tun
Da wird es noch sehr oft zu Diskussionen kommen, denn bei einigen Themen ist es eben nicht mit ein paar Befehlszeilen und Fachbegriffen getan.
Zumal ich dachte, es soll Einsteigergerecht sein, dazu gehört eben auch ein wenig Hintergrundwissen dazu.
Und was viel wichtiger ist, wenn schon permanent immer der selbe Fehler XY bei vielen Usern auftritt, kann man das doch auch direkt gleich als Hinweis mit dran packen.@apollon77 sagte in Doku node.js Update:
Optimieren, Kürzen, Verteilen, Verschieben u.ä. können wir immer noch in einem zweiten Schritt.
eben, denoch versucht man es ja so passend wie möglich umzusetzen.
daher,
da ich mir das nun nochmal in aller Ruhe zu Hause am Pc durchgelesen habe, bin ich dennoch etwas verwirrt@jey-cee sagte in Doku node.js Update:
Ich finde es anstregend in einem so Wuchtigen Text nach einer Anleitung zu suchen
Die einzelnen Passagen werden doch rechts oben im Menü aufgeschlüsselt, ein klick darauf und man ist beim entsprechenden Part.
siehe Beispiel
@jey-cee sagte in Doku node.js Update:
Ein Sinnvoller Aufbau könnte sein das zuerst die Einleitung kommt, dann der Ablauf mit Erklärung und am Ende die Anleitung.
- Einleitung ist vorhanden, (sollte zum Ausklappen sein, für denjenigen die es interessiert)
- Ablauf mit Erklärung ist ebenfalls vorhanden und ist doch sogleich die Anleitung, nur das die ensprechenden Befehle dazu direkt bei stehen.
Somit hat der Leser den direkten Bezug/Info zum Befehl.
klapp ich nun alles mögliche mittels Dropdown zu und klatsch am Ende die "Befehlskette" zum abarbeiten hin, liest doch kein Mensch zwischen den Zeilen und kopiert nur wieder blind heraus ohne zu wissen, was er da eigendlich macht.
-
@oliverio sagte in Doku node.js Update:
Du erstellst genau die gleiche Seite nach deinen Vorstellungen
So das hab ich jetzt mal gemacht, nur um zu Zeigen was ich meine.
Es gibt zu 100% Verbesserungsmöglichkeiten bei den Texten und es ist nicht Vollständig.
Für Mac fehlt die Anleitung ganz und Windows ist Unvollständig, aber die Zweite Anleitung war nötig um das Prinzip zu verdeutlichen.Außerdem habe ich deutlich mehr Links eingestreut, zum Teil sind auch Links drin mit Platzhaltern.
Ich seh keinen Sinn darin etwas zu beschreiben was jemand anders bereits beschrieben hat.Btw. das bisschen hat mich jetzt 5 Stunden gekostet und es ist weit weg von Perfekt. Das ist der Grund warum ich sowas normal nicht mache.
https://github.com/Jey-Cee/ioBroker.docs/blob/master/docs/de/install/updatenode.md
@crunchip sagte in Doku node.js Update:
liest doch kein Mensch zwischen den Zeilen und kopiert nur wieder blind heraus ohne zu wissen, was er da eigendlich macht.
Genau das passiert auch so wie du es geschrieben hast. Nur das die User dann halt schnell mal einen Befehl übersehen und damit zu 100% in Probleme Laufen. Da Spreche ich aus Erfahrung.
Übrigens finde ich das deine Einleitung sehr gut auf die Seite Architektur passen würde. Das was da jetzt zu Node.JS steht ist Mager.
-
@jey-cee sagte in Doku node.js Update:
nur um zu Zeigen was ich meine
ich danke dir für deine Mühe
ich habe es kompett gelesen und auch mehrmalsaber
@jey-cee sagte in Doku node.js Update:
zum Teil sind auch Links drin mit Platzhaltern.
Ich seh keinen Sinn darin etwas zu beschreiben was jemand anders bereits beschrieben hat.die Platzhalter führen in die Doku, die nicht gefüllt ist und laufen ins leere, da sehe ich das(mein) aktuelle Problem, wann wird diese Seite gefüllt. Deshalb habe ich das auch nicht verlinkt.
Nur noch auf Seiten zu verlinken, die man irgendwo im Netz findet, die der Linux Fremde dann auch wieder nicht versteht. Ich möchte den Einsteiger doch an die Hand nehmen, mit Beispiel zum Verständnis und mögliche Fehler zu vermeiden.
Desweiteren bin ich der Meinung, in dem Fall Thema Update Node.js sollte alles auf einer Seite sein und möchte nicht auf mehreren Seiten hin und herspringen müssen um mir alles zusammen zu suchen.
deinen Aufbau habe ich schon verstanden, doch machst du es dir damit recht einfach, denn Punkte wie
- Update innerhalb einer Version (apt update && apt upgrade)
ist auch sehr wichtig, gerade beim radar2 und ble Adapter) weil die benötigten setcup... Befehle gesetzt werden müssen, was mittlerweile auch der iob fix bereinigt - js-controller, nicht jeder ist auf aktuellem Stand, selbiges gilt fürs
- Betriebssystem
- Problemlösung, wenn es nicht geklappt hat, bzw wenn die Vorraussetzung gar nicht gegeben ist, wie in meiner unter Vorbereitung Punkt 1 zu finden
gerade im Bezug auf die richtigen Pfade, doppelte Installation/ verschiedene Versionsinstallationen, was sehr vebreitet ist, gehst du gar nicht ein. Deine Dokumentation geht vom reinen Idealfall aus.
gehe ich in den Laden und kaufe mir einen Verstärker, pack den zu Hause aus, darin finde ich ein zusammen gefaltetes Blatt mit der Aufschrift "Schnellinstallation", daneben liegt ein kleines Buch mit dem Titel "Benutzerhandbuch"
Was von beiden soll die Doku hier werden??
@jey-cee sagte in Doku node.js Update:
Übrigens finde ich das deine Einleitung sehr gut auf die Seite Architektur passen würde. Das was da jetzt zu Node.JS steht ist Mager.
stimme ich dir zu, jedoch gehört zur Architektur noch viel mehr dazu als Node.js, das ist ne andere Hausnummer,
ich habe mir bewusst das Thema Update Node.js herausgesucht - Update innerhalb einer Version (apt update && apt upgrade)
-
Mal abgesehen vom genauen Inhalt, Umfang und ob Verlinkung oder nicht... ich denke hier stehen zwei grundlegende Konzepte gegenüber:
- @crunchip's Ansatz, Befehle im Kontext von Erklärungen unterzubringen
- @Jey-Cee's Ansatz, erst zu erklären und dann kompakt die Befehle aufzulisten
Ich persönlich bevorzuge 2., weil es mmn. alle User gleichermaßen abholen kann:
- Die Profis, die wissen was sie tun und nur die Befehle nachschlagen wollen. Die können die Erklärung überspringen und sich aus den Befehlen das rauspicken, was sie brauchen.
- Die Anfänger, die erst mal genau lesen, was sie warum tun und danach das "wie".
- Und die Ungeduldigen, die sowieso nicht richtig lesen - die können wie die Profis die Befehle kopieren und ausführen. Da wird dann ggf. der ein oder andere Befehl zu viel ausgeführt, aber wenigstens keiner zwischen den textreichen Absätzen übersehen, was das troubleshooting im Anschluss einfacher macht
-
@crunchip sagte in Doku node.js Update:
da spricht nichts dagegen, die Art und Weise ist entscheidend. Statt "herab lassend" zu kritisieren, wäre es wünschenswert, wenn ein "alter Hase" dem "Neuling" konstruktiv und unterstützend unter die Arme greift.
Da bin ich bei Dir. Ich denke es war von @Jey-Cee nicht so "ruppig" gemeint wie man es lesen konnte
Vor allem bei diesem Thema "Doku" gibt es wahrscheinlich noch mehr Meinungen als bei anderen Themen und diese kommen aus "Zielgruppen-Sichten" (jeder gehört einer irgendwie an - oder mehrere). Da müssen wir uns bitte alle zwingen neutrales und konstruktives Feedback zu geben. Das würde ich mir wünschen.Gerade bezüglich auf den screen unten, Redis Datenbank, dachte ich mach dir einen gefallen, hab deine Infos aus dem Forum und den Rest aus dem Internet zusammen geklaubt, du hast mir noch Tpps gegeben dass das ein oder ander noch mit aufgenommen werden sollte, hast den ein oder anderen Satz noch etwas umformuliert und fertig war der Lack, zack und eine Seite mehr in der Doku, ohne gross Tam Tam
Und da ist eine super Idee und Danke dafür! Ja, wir haben einige "etablierte" pPosts im Forum die gut Vorlage für solche Dokus sein können.
-
@jey-cee sagte in Doku node.js Update:
https://github.com/Jey-Cee/ioBroker.docs/blob/master/docs/de/install/updatenode.md
Dieser Ansatz der Aufbereitung ist auch eine sehr gute Möglichkeit. Finde ich sehr übersichtlich und auch für die User Zielführend. Kontext als erstes,dann die Kommandos je nach Platform, dann Troubleshooting. macht für mkch vom Aufbau her Sinn.
Ich denke das sind genau die Diskussionen die wir neutral und zielgerichtet brauchen um "Best Practices" zu finden die wir dann auch auf andere Themen anwenden können.
-
@alcalzone sagte in Doku node.js Update:
Ich persönlich bevorzuge 2., weil es mmn. alle User gleichermaßen abholen kann:
und genau das bezweifle ich, dass damit auch Einsteiger abgeholt werden.
Ich behaupte mal, dass für dich als Hardcore-Entwickler der Blickwinkel ähnlich wie der von @Jey-Cee ist.@crunchip hat dazu ja bereits vieles geschrieben, wo ich aus Einsteigersicht nur zustimmen kann.
Für Profis und Ungeduldige mag die Version von @Jey-Cee die bessere sein. Aber geau so etwas hatte ich erwartet (und befürchtet)
-
@crunchip Als kleine Info: Der js-controller 4 wird nodejs Updates auch bei minor/patch Versionen erkennen und beim start die caps selbst so setzen wie es "iob fix" auch schon tut. Und der controller 4 sollte, wenn alles klappt, auch die "rebuild" Probleme bei "serialport" hinbekommen ...
Nichts desdo trotz sind die aktuellen Versionen draussen und ja der Artikel sollte auch solche Fälle abdecken
