NEWS

Neue Dokumentation ins nächste Level heben


  • Developer

    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:
    l1.png
    Dann kommt folgende Seite:
    l2.png

    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:

    1. Wie kann man neue (Unter)kapitel einfügen, also z.B. hier noch "Windows" unterhalb Linux ergänzen?
      wind.png
    2. Wo würde man das Thema JavaScript unterbringen, also von alter Doku:
      js.png
      Also zum einen die Erklärung des "JavaScript"-Adapters, die Verwendung, und dann Beispiel-Scripts?
    3. 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:
      github.png
    4. In der Doku sieht die Ansicht so aus (also Warnsymbol, dunkelblauer Strich links und hellblauer Hintergrund, etc.):
      dok1.png
      In Github allerdings so :
      dok2.png
      Wie weiß man denn dann, wie man richtig formatiert?
    5. 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.


  • Developer

    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.


  • Developer

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


  • Developer

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


  • Developer

    @Mic ja pass es an. Kaputt machen kann man nix, auf Github wird jede Änderung an einer Datei gespeichert, so kann man immer zurück zu einer früheren Version.


  • Developer

    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:
    vorg.png

    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:
    ghm.png


  • Developer

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


  • Forum Testing Most Active Global Moderator Administrators

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


  • Developer

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


  • Forum Testing Most Active Global Moderator Administrators

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


  • Developer

    Ok, danke Euch @Homoran und @Jey-Cee.

    Ich hab zunächst mal 2 Artikel überarbeitet, auch zum Testen für mich. Siehe


  • Forum Testing Most Active Global Moderator Administrators

    @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


  • Developer

    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?


  • Forum Testing Most Active Global Moderator Administrators

    @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!
    Screenshot_20190616-211426~2.png

    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


  • Developer

    Und die Seitennavigation dazu heißt "Tutorial", und nicht "Updates ☺
    konf.png
    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


  • Developer

    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.
    tut.png
    Dort via GitHub angepasst.


  • Forum Testing Most Active Global Moderator Administrators

    @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


  • Developer

    Gerne @Homoran, melde Dich einfach. Sorry für die Umstände die du hast, das macht es nicht leicht.
    Aber ich helfe gerne bei der Doku mit, cooles Konzept mit Github-Integration. Bekommen wir dank der Community schon gut hin.



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



Suggested Topics

1.8k
Online

30.9k
Users

37.8k
Topics

509.7k
Posts