Modul Dokumentation

Hallo zusammen,

dieses Thema ist etwas, was ich gerne angehen würde.
Mein Vorschlag:
Im Wiki eine Sektion „PHP Module“ vergleichbar mit „IPSLibrary für Anwender“ einführen.

Da könnte dann jedes Modul seine Doku ablegen.

Bisher ist im Wiki alles (?) auf Deutsch. Ist das OK so? Beruflich muss ich alles auf Englisch dokumentieren und daher passiert das bei mir fast automatisch… Was meint ihr dazu? Reicht Deutsch aus?
@ Paresy: Wie sieht es mit der Verbreitung von IPS im nicht Deutschsprachigen Raum aus?

Ich fänd es aber gut auf der jeweiligen Dokuseite eine vergleichbare Struktur zu haben.

Mein Vorschlag:
1) Zweck des Moduls
Grobe Beschreibung wofür das Modul gedacht ist und was man mit dem Modul erreichen kann, ohne ins Detail zu gehen.
2) Voraussetzungen
Wenn es abhängigkeiten gibt, sollte diese Aufgeführt sein
3) Installation/Konfiguration
URL des GIT repository
Screenshot vom Instanz Konfigurations Formular
Detaillierte Beschreibung aller Konfigurationsmöglichkeiten
4) Funktionen
Detaillierte beschreibung aller Funktionen des Moduls
5) Variablen
Beschreibung aller Variablen, die unterhalb einer Modulinstanz angelegt werden.
Bedeutung, möglicher Inhalt, was sonst noch interessant sein könnte.
6) Scripte
Beschreibung angelegter Scripte im Detail.
Was machen sie?
Werden sie regelmäßig ausgeführt?
7) Changelog
Auflistung was an welchem Datum geändert wurde.

Was meint ihr?
Ergänzungen, etwas überflüssiges dabei?
Ich würde mich auch bereiterklären mit meinem Sonos Modul anzufangen :wink:

Gruß,
Thorsten

Moin!

Wozu doppelt pflegen? Ich finde nur wichtig, dass im GitHub in der Readme alles drin steht. Da hat der User dann Zugriff drauf und IPS selbst könnte darauf auch zugreifen.

Sieht bei mir z.B. so aus (von Nall chan abgeschaut :D):
BayaroX/BY_Enigma2BY · GitHub
BayaroX/BY_BundesligaTabelle · GitHub
BayaroX/BY_BatterieMonitor · GitHub

Was ich nicht drin habe, dass sind die Variablen und welchen Sinn die haben. Bzw. hab ich es nur teilweise drin. Und die Skripte hab ich nicht drin, aber da hab ich auch noch keine „extra“, sonst würde ich die wohl auch in der Readme erwähnen…

Was vlt. noch nicht schlecht wäre, wenn man den Changelog in einer extra Datei machen würde (mit einem bestimmten Namen)…falls IPS die mal einzeln auswerten will, um beim Update da etwas anzeigen zu können.

Da müsste @paresy etwas dazu sagen…

Grüße,
Chris

Ich bin auch eigentlich ein Verfechter des WiKi.
Allerdings finde ich die Doku hat dort nix zu suchen.
Die sollte schon im Repro liegen, mit der Hoffnung das IPS die irgendwie in der Console darstellt.
Das readme wird ja eh mit geclont wenn IPS das Modul aus dem Repro clont.
Aber die Übersicht der Module könnte man ergänzen, sowie Workarounds, Hilfsfunktionen, Best practice etc…
Ich komme aber momentan noch nicht mal dazu den passenden Thread zu pflegen… Asche über mein Haupt :frowning:
Michael

Ich bin auch mehr für das Readme im Github. Da das ohnehin bei der Modulinstallation gezogen wird, müsste es es doch relativ einfach sein in der Hilfe der Konsole einen Link zur Anzeige des jeweiligen Readmes zu generieren. Alles andere wäre doppelt.

My 2 Cents
Tommi