Refactor Plugin Documentation

[rhuss]

Based on the discussion at #665 (comment), let's consider refactoring the current documentation in plugin.md.

@andig proposal is the introduction of a top-down structure like:

• Integration von "custom" Geräten
• Unterschiedliche "custom" Gerätetypen (meter, charger, vehicle)
• Plugins (Auswahl, Konfiguration)
• Beispiele

Based on that, I did an initial mockup in this Doc, but there are still gaps (i.e. explaining the second-level used in entities like meter or charger).

Since the documentation will be drafted in German and translated into English, let's continue this issue in German.

---

Das Dokument ist offen für Kommentare, daher bitte direkt in dem Dokument kommentieren. Falls wir uns dann auf eine Version einigen koennen wuerde ich es dann nach Markdown transferrieren und auch uebersetzen.

Die Frage ist aber auch, ob es reicht nur plugins.md zu refaktorieren, oder sollte man noch groesser ansetzen und z.b. das Schema an zentralerer Stelle dokumentieren ? Da koennte ich mir auch eine Refaktorierung vorstellen, z.b. "Referenz" in "Konfiguration" verschiebene, da vor "evcc.yaml" noch einen allgemeine Seite, das die Struktur des Schemas erklaert. Das wuerde ich auch noch nach oben in ToC ziehen, da die Sektion "Geraete" ja schon viele Vorwaertsreferenzen auf YAML Elemente enthaelt. Also in etwa so

Einfuehrung
  - hier der Unterpunkte von "Funktionen"
  - ...
Installation
  - ...
Konfiguration
  - Uebersicht (hier die Struktur des Schemas erklaeren)
  - evcc.yaml
  - Plugins
  - Modbus 
  - CLI
Geraete
  - ...
Integrationen
  - ...
FAQ
Sponsorship

Was meint ihr ? Nur erstmal an plugins.md arbeiten oder insgesamt umbauen ?

[naltatis]

Ich find die Initiative gut. Auch die, noch mal die Gesamtstruktur zu hinterfragen. Ich würd hier aber inkrementell vorgehen und hätte ein etwas anderes Zielbild.

Den "Referenz" Punkt sollten wir Stück für Stück ausdünnen. Wir haben kürzlich auch MQTT und REST in den neuen Integrationen Menüpunkt überführt. Den Punkt "CLI" und "evcc.yaml" würde ich da weiterhin lassen. Wobei evcc.yaml früher oder später ja komplett wegfallen wird. Dementsprechend würde ich auch nicht zu viel Energie in neue Doku für Dinge investieren, die nur für die evcc.yaml relevant sind. Erklärungen für konkrete Eigenschaften wie bspw. interval wandern direkt ins Config UI. Für komplexere Eigenschaften und Erklärungen zu Parametern und Feldern können wir dann aus der UI raus auch direkt die Dokuseite, die die Funktion erklärt, verlinken. Also eher nach Themen strukturiert als Glossar-Style wie heute.

Thematisch würde ich "Plugins" aktuell als Unterpunkt von "Geräte" sehen. So nach dem Motto: "Dein Gerät ist nicht dabei? Hier erfährst du, wie du ein eigenes anlegst". Nur für diese sind sie ja relevant. Das Wording ist noch nicht super, weil wir auch Tarife "Geräte" nennen.

Um auf deine Frage zu antworten. Lass uns erstmal "nur" mit Plugins starten. Die würde ich aber dann auch direkt in "Geräte > Plugins" umhängen.

Kurz zum Kontext der Migration von evcc.yaml zu Config UI: Die konkreten YAML-Blöcke für Geräte-Plugins und erweiterte Funktion wie ModbusProxy, Lastmanagement werden bis auf Weiteres ja relevant bleiben. Der Pflegeort wird dann halt ein Textfeld in Config UI anstatt der evcc.yaml sein.

[andig]

Thematisch würde ich "Plugins" aktuell als Unterpunkt von "Geräte" sehen.

Aber: charger/meter/tariff sind unterschiedliche "Geräte" mit unterschiedlichen Properties. Plugins funktionieren aber für alle gleich. Hier halte ich DRY für sehr sinnvoll. Irgendwo muss der Punkt "Plugins" hin.

Die würde ich aber dann auch direkt in "Geräte > Plugins" umhängen.

Gerne

Kurz zum Kontext der Migration von evcc.yaml zu Config UI:

Ich würde generell versuchen einzelne PRs so klein wie möglich zu halten- schneller zu reviewen/ mergen und weniger Frust beim Ersteller! Lieber viele kleine Schritte als gar keinen grossen :O

[rhuss]

Alles klar, dann bleibe ich bei der Plugin Dokumentation.

Ich werde versuchen auch für die verschiedenen Unterbereiche (power, energy, ... je nach Gerätetyp) in einer Tabelle erfassen ob man dafür lesende und/oder schreibende Plugins nutzen kann.

Aber: charger/meter/tariff sind unterschiedliche "Geräte" mit unterschiedlichen Properties. Plugins funktionieren aber für alle gleich.

Dazu kommen noch die meesenger beim Verschicken von Events. Ich wuerde des daher eher nicht unter Geraete aufhaengen, sondern vielleicht doch top-level lassen ?

[rhuss]

Ich hab mal an der Struktur gearbeitet und habe mich an einer Tabelle versucht, die neben dem Geraettyp auch die moeglichen Eigenschaften, die aus einem Plugin gelesen werden koennen beschrieben. Ich denke so ein Uebersicht kann recht hilfreich sein, wenn dann noch entsprechende verlinkt. Sie entspricht auch dem anvisierten top-down approach mehr.

@andig @naltatis wenn ihr ueber das doc mal kurz gehen koenntet und sagen ob die Struktur so passen wuerde, dann wuerde ich das naechste Woche als PR vorschlagen.

Zusammengefasst faende ich so eine top-down Struktur ganz sinnvoll:

• Einleitung
• Uebersicht moeglicher Verwendung von Plugins (die neue Tabelle)
• Auflistung aller Plugins in Uebersichtstabelle
• Beschreibung der allgemeine Pluginkonfiguration, die für alle Plugins gilt (pipelines, variablen ersetzung, hier dann auch: auto-konversion xml -> json)
• Individuelle Beschreibung jedes Plugins:
  • Beschreibung
  • Tabelle moeglicher Parameters (ausser der pipeline parameter)
  • Lesen
    • Beschreibung
    • Beispiel
  • Schreiben
    • Beschreibung
    • Beispiel

[naltatis]

@rhuss Ich bin das Dokument durchgegangen. Find ich gut. Über die genauen Details können wir dann ja im PR noch mal sprechen. Aber der Aufbau ist gut.

Dazu kommen noch die meesenger beim Verschicken von Events. Ich wuerde des daher eher nicht unter Geraete aufhaengen, sondern vielleicht doch top-level lassen ?

Dann würde ich vorschlagen, dass wir Plugin und mittelfristig auch Messaging (aktuell noch unter evcc.yaml) nach "Integrationen" verschieben. Das passt für mich insofern, weil das beides eher Advanced Themen sind. Als Top-Level würde ich Plugins (zumindest heute) noch nicht sehen.

Messaging könnte später mal in den "Funktionen" Bereich wandern, wenn wir die Einrichtung schön via UI umgesetzt haben. Aktuell ist "messaging" ja eher noch etwas bastelig.

[rhuss]

Sorry, bin etwas verspaetet. Ich denke aber, dass ich bis zum Wochenende dazukomme.