Neue Dokumentation ins nächste Level heben
-
Hallo zusammen,
vielen Dank für die neue Dokumentation.
Ich finde es allerdings ziemlich kritisch, dass diese noch so lückenhaft ist, das schreckt doch viele potenzielle Neueinsteiger ab (ich hätte mich bei dieser Doku sicherlich nicht für ioBroker entschieden). So wie die Doku jetzt aussieht, wirkt sie wie eine dieser vielen toten Wikis im Netz.Sorry für diese Kritik, ich schätze sehr die Leistungen und auch das Konzept für die neue Doku. Aber das war vielleicht ein zu radikaler Cut, weil viele, wenn auch veraltete, Inhalte, nicht übernommen und einfach nicht vorhanden sind.
Dazu kommt, dass man teilweise nicht sieht, wo man sich in der Doku befindet, Beispiel:
Man klickt hier auf den Link:
Dann kommt folgende Seite:
Man sieht also nicht, in welchem Unterkapitel man sich befindet. Wünschenswert wäre eine Breadcrumb-Navigation oben zur Anzeige, also etwa:
"Startseite > Thema > Unterthema"Ich hab zunächst mal folgenden Vorschlag:
So schnell wie möglich alle "Baustellen-Seiten" mit den alten Inhalten oder Forenbeiträgen verlinken. Damit sind dann die User nicht völlig "lost".Ich helfe gerne mit bzw. fange gerne einfach damit mal an
Fragen:
- Wie kann man neue (Unter)kapitel einfügen, also z.B. hier noch "Windows" unterhalb Linux ergänzen?
- Wo würde man das Thema JavaScript unterbringen, also von alter Doku:
Also zum einen die Erklärung des "JavaScript"-Adapters, die Verwendung, und dann Beispiel-Scripts? - Ich scheitere schon an einem einfachen Update der Doku. Der Styleguide sagt:
"Dokumente beginnen immer mit einer Überschrift in der Ebene H1".
Tatsächlich sieht das dann in Github so aus, beginnt also nicht mit Überschrift:
- In der Doku sieht die Ansicht so aus (also Warnsymbol, dunkelblauer Strich links und hellblauer Hintergrund, etc.):
In Github allerdings so :
Wie weiß man denn dann, wie man richtig formatiert? - Styleguide verweist auf Browser-Plugin für Github. Ich habe EditorConfig installiert für Chrome, aber sehe keinen Unterschied. Problem ist wohl vor der Tastatur Würde mir eine Anleitung wünschen. Oder gibt es gar einen WYSIWYG-Editor?
Dies schon mal die ersten Fragen und Stolpersteine beim Mithelfen.
Danke.
- Wie kann man neue (Unter)kapitel einfügen, also z.B. hier noch "Windows" unterhalb Linux ergänzen?
-
Mal sehen wo ich dir weiterhelfen kann.
Zu 1.: Dafür muss im entsprechenden Pfad auf Github eine neue Seite erstellt werden.
Zu 2.: das passt am besten unter Tutorials.
Zu 3.: H1 bedeutet Überschrift ersten Grades. Das andere darüber ist die Kopfzeile. Das ist sehr Technisch ausgedrückt in der Doku für dir Doku.
Zu 4.: Der Kopf und diese Hinweisboxen werden vom der Doku Seite interpretiert, das kennt der github editor nicht. Der Rest ist soweit ich das bisher gesehen habe reines Markdown und sollte von Github richtig interpretiert werden.
Zu 5.: Plugin sollte für GitHub nicht nötig sein, da ist das schon seitens Github implementiert.
Die von dir angesprochenen Punkte kann man in der Doku verbessern. Danke für dein Feedback.
Ich hoffe das du weiter machst und Hilfst die Doku weiter zu verbessern. Vieles kannst du direkt selbst verbessern in dem du unklare Passagen überarbeitest.
Persönlicher Support
Spenden -> paypal.me/J3YC33 -
Vielen Dank für Deine rasche Antwort, das hilft sehr.
@Jey-Cee sagte in Neue Dokumentation ins nächste Level heben:
Ich hoffe das du weiter machst und Hilfst die Doku weiter zu verbessern. Vieles kannst du direkt selbst verbessern in dem du unklare Passagen überarbeitest.
Sehr gerne. Natürlich
Ich möchte ja konstruktiv mithelfen, daher mein konstruktives Feedback und die Fragen. Wir müssen das gemeinsam weiter bringen.Die Doku-Challenge ist, wie rapide hier im ioBroker Neuerungen eingebracht werden seitens Entwicklung (neue oder verbesserte Adapter, das System an für sich, etc.), was mega für ioBroker ist, aber halt auch die Herausforderung für die Doku ist.
Daher sollten sich viele einbringen, bei der Doku mitzuarbeiten, und ich fasse mich da an die eigene Nase.
Aber am Ende des Tages zählen Taten, und keine Worte. -
Mal sehen wo ich dir weiterhelfen kann.
Zu 1.: Dafür muss im entsprechenden Pfad auf Github eine neue Seite erstellt werden.
Zu 2.: das passt am besten unter Tutorials.
Zu 3.: H1 bedeutet Überschrift ersten Grades. Das andere darüber ist die Kopfzeile. Das ist sehr Technisch ausgedrückt in der Doku für dir Doku.
Zu 4.: Der Kopf und diese Hinweisboxen werden vom der Doku Seite interpretiert, das kennt der github editor nicht. Der Rest ist soweit ich das bisher gesehen habe reines Markdown und sollte von Github richtig interpretiert werden.
Zu 5.: Plugin sollte für GitHub nicht nötig sein, da ist das schon seitens Github implementiert.
Die von dir angesprochenen Punkte kann man in der Doku verbessern. Danke für dein Feedback.
Ich hoffe das du weiter machst und Hilfst die Doku weiter zu verbessern. Vieles kannst du direkt selbst verbessern in dem du unklare Passagen überarbeitest.
@Jey-Cee sagte in Neue Dokumentation ins nächste Level heben:
Zu 3.: H1 bedeutet Überschrift ersten Grades. Das andere darüber ist die Kopfzeile. Das ist sehr Technisch ausgedrückt in der Doku für dir Doku.
Soll man diese Kopfzeile anpassen (da steht ja dann ein Datum), oder ignorieren?
-
@Jey-Cee sagte in Neue Dokumentation ins nächste Level heben:
Zu 3.: H1 bedeutet Überschrift ersten Grades. Das andere darüber ist die Kopfzeile. Das ist sehr Technisch ausgedrückt in der Doku für dir Doku.
Soll man diese Kopfzeile anpassen (da steht ja dann ein Datum), oder ignorieren?
-
Ok, danke.
@Jey-Cee sagte in Neue Dokumentation ins nächste Level heben:
Zu 1.: Dafür muss im entsprechenden Pfad auf Github eine neue Seite erstellt werden.
Wie ist denn hier die Vorgehensweise? Also angenommen, ich will hier "Windows" unterhalb Linux hinzufügen:
Durch Klick auf "Auf Github ändern" wird ja eine neue Fork erstellt. Nur hier weiß ich dann nicht, wie ich weiter vorgehe, und welche Auswirkung es hat, wenn ich etwa jetzt eine neue Seite dort erstelle. Sind ja doch viele Dateien hier:
-
Ok, danke.
@Jey-Cee sagte in Neue Dokumentation ins nächste Level heben:
Zu 1.: Dafür muss im entsprechenden Pfad auf Github eine neue Seite erstellt werden.
Wie ist denn hier die Vorgehensweise? Also angenommen, ich will hier "Windows" unterhalb Linux hinzufügen:
Durch Klick auf "Auf Github ändern" wird ja eine neue Fork erstellt. Nur hier weiß ich dann nicht, wie ich weiter vorgehe, und welche Auswirkung es hat, wenn ich etwa jetzt eine neue Seite dort erstelle. Sind ja doch viele Dateien hier:
@Mic es hat erst mal keine Auswirkung außer das es eine neue Datei gibt. Die wird auch erstmal separat erstellt und wird mit Pull Request als Vorschlag an die Doku gegeben.
Dann wird sie nochmal geprüft, Formatierung und Inhaltlich, wobei es keine intensiv Prüfung ist. Wenn alles passt wird der PR angenommen, gilt auch für Änderungen an vorhandenen Dateien.Allgemein sollte der Name der Datei nicht lang, aber Aussagekräftig sein. Die Namen sind immer Englisch und enden mit .md
In dem Fall Windows existiert eine, erst mal rein schauen was drin ist und ob man die Überbeiten muss/kann.
Das Verzeichnis in der Doku wird manuell erstellt, soweit ich das weis, deshalb tauchen auch nicht alle Dateien in der Doku auf.Eine neue Datei erstellt man mit dem Button "Create New file" rechts oben. Die Kopfzeile holt man sich am einfachsten aus einer anderen Datei.
-
Mal sehen wo ich dir weiterhelfen kann.
Zu 1.: Dafür muss im entsprechenden Pfad auf Github eine neue Seite erstellt werden.
Zu 2.: das passt am besten unter Tutorials.
Zu 3.: H1 bedeutet Überschrift ersten Grades. Das andere darüber ist die Kopfzeile. Das ist sehr Technisch ausgedrückt in der Doku für dir Doku.
Zu 4.: Der Kopf und diese Hinweisboxen werden vom der Doku Seite interpretiert, das kennt der github editor nicht. Der Rest ist soweit ich das bisher gesehen habe reines Markdown und sollte von Github richtig interpretiert werden.
Zu 5.: Plugin sollte für GitHub nicht nötig sein, da ist das schon seitens Github implementiert.
Die von dir angesprochenen Punkte kann man in der Doku verbessern. Danke für dein Feedback.
Ich hoffe das du weiter machst und Hilfst die Doku weiter zu verbessern. Vieles kannst du direkt selbst verbessern in dem du unklare Passagen überarbeitest.
@Jey-Cee sagte in Neue Dokumentation ins nächste Level heben:
Zu 1.: Dafür muss im entsprechenden Pfad auf Github eine neue Seite erstellt werden.
Das reicht allei e nicht, auch das Menü muss angepasst werden.
Habe gestern schon in einem anderen Thread einiges dszu geschrieben.Und vieles existiert bereits und ist im Moment "nur" nicht in die Struktur integriert.
Bin leider aus gesundheitlichen und dienstlichen Gründen nicht dazu gekommen, dass zu prüfen.
kein Support per PN! - Fragen im Forum stellen -
Benutzt das Voting rechts unten im Beitrag wenn er euch geholfen hat.
Das Forum freut sich über eine Spende. Benutzt dazu den Spendenbutton oben rechts. Danke!
der Installationsfixer: curl -fsL https://iobroker.net/fix.sh | bash - -
@Jey-Cee sagte in Neue Dokumentation ins nächste Level heben:
Zu 1.: Dafür muss im entsprechenden Pfad auf Github eine neue Seite erstellt werden.
Das reicht allei e nicht, auch das Menü muss angepasst werden.
Habe gestern schon in einem anderen Thread einiges dszu geschrieben.Und vieles existiert bereits und ist im Moment "nur" nicht in die Struktur integriert.
Bin leider aus gesundheitlichen und dienstlichen Gründen nicht dazu gekommen, dass zu prüfen.
@Homoran sagte in Neue Dokumentation ins nächste Level heben:
Das reicht allei e nicht, auch das Menü muss angepasst werden.
Ja aber es ging darum was die Helfer machen müssen, nicht wir. Deswegen halte ich solche Sachen raus, es soll ja so einfach wie möglich sein.
Persönlicher Support
Spenden -> paypal.me/J3YC33 -
@Homoran sagte in Neue Dokumentation ins nächste Level heben:
Das reicht allei e nicht, auch das Menü muss angepasst werden.
Ja aber es ging darum was die Helfer machen müssen, nicht wir. Deswegen halte ich solche Sachen raus, es soll ja so einfach wie möglich sein.
@Jey-Cee sagte in Neue Dokumentation ins nächste Level heben:
was die Helfer machen müssen,
Eben!
Bevor irgendwelche nur Seiten geschrieben werden sollte immer geklärt werden wo die hin soll und ob das möglich ist.
Sonst machen sich die Helfer unnötige Arbeit!
Das gleiche gilt für existente aber irgendwo verschollene Seiten.
Ich werde sobald ich nach der Dienstreise die Zeit finde, versuchen solche Leichen wieder sichtbar zu machen.
Daher würde es erstmal reichen fehlende Seiten (besonders wenn sie in der alten Doku existierten) aufzulisten/zu melden!
-
@Mic
Danke!Aber:
Auffällig ist, dass der Titel laut Seitenleiste "Tutorial" unter dem Hauptpunkt "Tutorials" ist, aber der Dateiname "updates.md". Sollte vielleicht auch gelegentlich korrigiert werden.
Das ist was ich meinte.
Da steht (oder soll stehen) die geplante oder im Datennirvana verschollene Seite zum Tutorial für das korrekte updaten hinter.Der Einfachheit halber heißen die Menüpunkte immer gleich und werden automatisch umbenannt wenn der Titel im Header der Datei eingetragen wird
-
Im Header der Datei steht ja "Tutorial":
--- title: "Tutorial" lastChanged: "14.09.2018" ---@Homoran sagte in Neue Dokumentation ins nächste Level heben:
Der Einfachheit halber heißen die Menüpunkte immer gleich und werden automatisch umbenannt wenn der Titel im Header der Datei eingetragen wird
Bedeutet also, wenn ich den Header-Titel z.B. von "Tutorial" in "JavaScript-Tutorial" ändere, dass ihr dann den Menüpunkt in der Doku, also links in der Navigation ersichtlich, automatisch anpasst?
Oder wie sollen wir solche Änderungen aktiv mitgestalten? Oder einfach einen Beitrag hier im Forum? -
Im Header der Datei steht ja "Tutorial":
--- title: "Tutorial" lastChanged: "14.09.2018" ---@Homoran sagte in Neue Dokumentation ins nächste Level heben:
Der Einfachheit halber heißen die Menüpunkte immer gleich und werden automatisch umbenannt wenn der Titel im Header der Datei eingetragen wird
Bedeutet also, wenn ich den Header-Titel z.B. von "Tutorial" in "JavaScript-Tutorial" ändere, dass ihr dann den Menüpunkt in der Doku, also links in der Navigation ersichtlich, automatisch anpasst?
Oder wie sollen wir solche Änderungen aktiv mitgestalten? Oder einfach einen Beitrag hier im Forum?@Mic sagte in Neue Dokumentation ins nächste Level heben:
Bedeutet also, wenn ich den Header-Titel z.B. von "Tutorial" in "JavaScript-Tutorial" ändere, dass ihr dann den Menüpunkt in der Doku, also links in der Navigation ersichtlich, automatisch anpasst?
Ja!
Aber bitte nicht in der Datei updates.md!
Wie du siehst heißt die Datei updates.md und bevor du deinen Text getippt hast heißt es in der Hauptüberschrift:
Durchführen von Updates
-
Und die Seitennavigation dazu heißt "Tutorial", und nicht "Updates
Daher hab ich dort die Änderungen eingebaut, ohne Dateinamen zu beachten.
Daher meine Frage. Also wo darf ich ändern, wo nicht, und was hat es dann für eine Auswirkung? Dateien umbenennen mache ich natürlich nicht.Übrigens "Durchführen von Updates" wird gar nicht angezeigt, nur im Editor
-
Vielleicht noch mal zu meiner Vorgehensweise:
Ich möchte ein paar Links zur Doku hinzufügen, um es den Anwendern zu erleichtern. Lt. https://forum.iobroker.net/post/271751 am besten JavaScript unter Tutorials. Da es sehr wenig Unterpunkte gibt, hab ich die quasi leere Seite "Tutorial" genommen.
Dort via GitHub angepasst. -
Und die Seitennavigation dazu heißt "Tutorial", und nicht "Updates
Daher hab ich dort die Änderungen eingebaut, ohne Dateinamen zu beachten.
Daher meine Frage. Also wo darf ich ändern, wo nicht, und was hat es dann für eine Auswirkung? Dateien umbenennen mache ich natürlich nicht.Übrigens "Durchführen von Updates" wird gar nicht angezeigt, nur im Editor
@Mic sagte in Neue Dokumentation ins nächste Level heben:
Und die Seitennavigation dazu heißt "Tutorial", und nicht "Updates
Weil es, wie du schon gemerkt hast, so im Header steht.
Ein pullrequest bezieht sich aber immer auf die Datei.
Wenn du mehr machen willst melde ich mich Ende der Woche Mal.
Bin im Moment dienstlich unterwegs und nur am Handy im Hotel -
Nachdem ich die Doku zum "Kernkonzept" auf Github etwas überarbeitet habe, was auch durch @Bluefox auf Github "merged" wurde, vermisse ich die Änderungen in der Doku https://www.iobroker.net/#de/documentation/dev/objectsschema.md.
Hey! Du scheinst an dieser Unterhaltung interessiert zu sein, hast aber noch kein Konto.
Hast du es satt, bei jedem Besuch durch die gleichen Beiträge zu scrollen? Wenn du dich für ein Konto anmeldest, kommst du immer genau dorthin zurück, wo du zuvor warst, und kannst dich über neue Antworten benachrichtigen lassen (entweder per E-Mail oder Push-Benachrichtigung). Du kannst auch Lesezeichen speichern und Beiträge positiv bewerten, um anderen Community-Mitgliedern deine Wertschätzung zu zeigen.
Mit deinem Input könnte dieser Beitrag noch besser werden 💗
Registrieren Anmelden294
Online32.8k
Benutzer82.9k
Themen1.3m
Beiträge