Modul-Dokumentation in commandref oder wiki?

Begonnen von tupol, 18 März 2018, 11:24:23

Vorheriges Thema - Nächstes Thema

tupol

Hallo Entwickler und Wiki-Pfleger,

ich habe noch keine Diskussion zu diesem Thema gefunden.
Die Modul-Dokumentation läuft derzeit über das Perl-Modul selbst. Ich persönlich finde es sehr schwierig, sie zu pflegen. Insbesondere da es viele Formatierungs-Restriktionen gibt, man HTML nutzen muss und man dadurch nicht sofort sieht, was man eintippt. Typisches Fehler-Beispiel bei mir: Umlaute

Dagegen komme ich mit der Wiki sehr viel besser zurecht. Dort kann man auch mal ins Detail gehen und zu anderen Beschreibungen verlinken.

Es ist leider auch ein erheblicher Aufwand, einen Teil der Beschreibungen im Modul selbst und alle Details in der Wiki zu pflegen. Eines von beiden vernachlässige ich oft. Ich bin deshalb am Überlegen, in die commandref nur noch einen Link auf die Wiki zu setzten und alles dort zu beschreiben.

Was denkt ihr darüber?

Gruß
tupol

NB: Die commandref ist inzwischen auch ein wahres Ungetüm.
FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

Dr. Boris Neubert

Globaler Moderator, Developer, aktives Mitglied des FHEM e.V. (Marketing, Verwaltung)
Bitte keine unaufgeforderten privaten Nachrichten!

tupol

FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

Dr. Boris Neubert

Hallo,

für mich ist das eine verwandte Fragestellung: wo wird die Doku gepflegt? Als Entwickler gehört für mich die Doku (Anwenderdoku, Entwicklerdoku) zum Modul. Beim Wiki kann ich nie sicher sein, dass der Stand der Doku dem Stand des Moduls entspricht und der Inhalt wirklich richtig ist.

Viele Grüße
Boris
Globaler Moderator, Developer, aktives Mitglied des FHEM e.V. (Marketing, Verwaltung)
Bitte keine unaufgeforderten privaten Nachrichten!

tupol

Ich verstehe Deine Prinzipienfestigkeit, aber das greift meine Argumentation nicht auf.

Zudem bin ich vermutlich weniger prinzipienfest, da ich kein professioneller Entwickler bin, sondern einfach nur Spaß an der Sache habe.
FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

gandy

Das würde sich m.E. aber elegant lösen lassen, wenn der Wiki Artikel Bezug auf die darin dokumentierte Version des Moduls nimmt.  Würde auch bei der Entwickler Doku helfen. Dann kann jeder leicht entscheiden, wie weit er dem Artikel trauen möchte.
fhem (svn) auf i5-4210U NUC
2x HMLAN, 19x HM-SEC-RHS, 15x HM-LC-Bl1PBU-FM, etc.
ODYS Neron Tablet / Android 4.2
Samsung Galaxy Tab 2 10.1N / Android 4.1.2
Samsung Galaxy Note / Android 6.0.1

rudolfkoenig

Der commandref Eintrag sollte das beschreiben, was das Modul kann, im UNIX man manier, d.h. kurz und vollstaendig, und sollte vom Entwickler erstellt werden. Die Einschraenkung des HTMLs ist Absicht: man sollte nur Text schreiben, und es es sollte ein Wettbewerb um Aufmerksamkeit mit bunt/gross/fett/blinken etc verhindern.

Das Wiki enthaelt Beispiele/HOWTOs, beschreibt Hintergrundwissen und wird am besten nicht vom Entwickler erstellt, da fuer ihn haeufig bestimmte Aspekte so selbstverstaendlich sind, dass er sie nicht erwaehnt.

ZitatIch bin deshalb am Überlegen, in die commandref nur noch einen Link auf die Wiki zu setzten und alles dort zu beschreiben.
Achtung: das fuehrt evtl. dazu, dass das Modul nach contrib verschoben wird.

ZitatNB: Die commandref ist inzwischen auch ein wahres Ungetüm.
Mit "attr global commandref modular" kann man die schlanke Version verwenden. Und man kann die Modulspezifische Hilfe mit Klick auf "Device specific help" in der Detailansicht eines FHEM-Geraetes aufrufen, ohne den Rest von commandref anzuzeigen.

Thorsten Pferdekaemper

Hi,
für mich ist HTML einfacher als die Wiki-Sprache. D.h. ich könnte die ganze Argumentation genau anders herum aufziehen. Ich sehe im Wiki ganz und gar nicht sofort, wie das, was ich da tippe, nachher aussieht. In HTML habe ich dagegen eine sehr gute Vorstellung davon.
Meiner Meinung nach ist es ganz gut so, im Modul selbst eine Kurzreferenz zu haben und wenn man dann noch mehr zu sagen hat, dann macht man das im Wiki.
Worüber man meiner Meinung nach diskutieren könnte, das ist ob alles zwingend in einer Datei zu sein hat, aber das ist eher eine Kleinigkeit.
Gruß,
   Thorsten
FUIP

Wuehler

Ich persönlich finde die kurze und knappe Doku im Modul gut und hilfreich. Wenn man sie nicht versteht  bekommt man dadurch zumindest Hinweise, wonach man in Wiki oder Forum suchen sollte.
Aus persönlicher Erfahrung kann ich sagen, dass ich mittlerweile ,,device specific help" oft verwende. Zu Beginn war der Link ganz unten auf der Seite nie im Blickfeld und ich hatte eine weitere Seite mit der kompletten commandref offen. Und da braucht  man aufgrund des Umfangs doch manchmal (zumindest gefühlt) etwas länger bis man findet was man sucht. Nach einer Anpassung im Modul teste ich damit auch gleich wie die commandref dann aussieht.
Vorschlag: ,,device specific help" aufwerten und einen Link weiter oben anbieten. ZB bei den getter und settern. Und / oder bei der Attributauswahl.

Zusammengefasst: ich bin für eine unix-like knappe commandref als modulbeschreibende Dokumentation.
Im Wiki wird eher die Verwendung eines Moduls beschrieben. Da wäre es hilfreich, wenn an einem Beispiel ein Datum steht, so dass man daran abschätzen kann, ob das Beispiel wahrscheinlich noch funktioniert.

tupol

Das Argument über den aktuellen Zustand der Wiki greift nicht ganz. Der Grund dafür ist ja gerade die doppelte Datenhaltung, die ich angesprochen habe.

Was aber tatsächlich für die commandref spricht, ist, dass ins Modul nur der Autor schreiben kann.

Größer und bunter ist auch nur die halbe Wahrheit. Man erhöht mit Formatierungen normalerweise die Lesbarkeit von Texten. Natürlich kann man das auch missbrauchen. Deshalb gibt es ja in WIKIs auch Einschränkungen, die aber meiner Meinung trotzdem eine viel höhere Lesbarkeit hat als die commandref.

Prinziell bin ich bei den Modulen mit der derzeitigen commandref (und auch mit manpages von Unix) nicht glücklich. Zu grob, zu unübersichtlich, zu schlecht lesbar. Bin aber kein ITler sondern eher ein Anwender.

Ich werde mir dann wohl das Verschieben ins contrib mal durch den Kopf gehen lassen. Ist vielleicht die beste Lösung.

Noch eine Frage: Warum muss ich eigentlich immer die Umlaute in HTML korrigieren? Könnte man nicht besser die code-page ändern?

Gruß
tupol
FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

tupol

Zitat von: Thorsten Pferdekaemper am 18 März 2018, 12:19:41
für mich ist HTML einfacher als die Wiki-Sprache. D.h. ich könnte die ganze Argumentation genau anders herum aufziehen. Ich sehe im Wiki ganz und gar nicht sofort, wie das, was ich da tippe, nachher aussieht. In HTML habe ich dagegen eine sehr gute Vorstellung davon.
Meiner Meinung nach ist es ganz gut so, im Modul selbst eine Kurzreferenz zu haben und wenn man dann noch mehr zu sagen hat, dann macht man das im Wiki.
Worüber man meiner Meinung nach diskutieren könnte, das ist ob alles zwingend in einer Datei zu sein hat, aber das ist eher eine Kleinigkeit.

Dafür würde ich Syntax-Highlighting für perl und html benötigen. Kann das Dein Editor?

Das mit der Kurzreferenz finde ich einen guten Kompromiss. Beibt die Frage, was man unter Kurzreferenz versteht? Kannst Du es definieren?

Wie würdest Du die "Kleinigkeit" bzgl. dem commandref-Ungetüm denn lösen?
FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

rudolfkoenig

ZitatNoch eine Frage: Warum muss ich eigentlich immer die Umlaute in HTML korrigieren? Könnte man nicht besser die code-page ändern?
Ich rate: dein Editor verwendet latin-1 (ISO-8859-1). FHEMWEB deklariert in der ausgelieferten Seite UTF-8 als charset, und wir bleben auch dabei.
Also entweder musst du dein Editor auf UTF-8 stellen, oder (was ich bevorzuge), schreibst die Umlaute in der HTML-Notation (ä Ä &szlig etc), womit dann alle zurechkommen. Ja, die Nachteile sind mir auch bekannt.

tupol

FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

tupol

@Rudi: Was sind die Konsequenzen für die Anwender bei einer Verschiebung ins contrib? Bekommen die noch mit, wenn ich Bugs entferne oder Features hinzufüge?
FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

Benni

Zitat von: tupol am 18 März 2018, 15:05:48
@Rudi: Was sind die Konsequenzen für die Anwender bei einer Verschiebung ins contrib?

contrib wird nicht per update verteilt.

Thorsten Pferdekaemper

Zitat von: tupol am 18 März 2018, 13:49:43
Dafür würde ich Syntax-Highlighting für perl und html benötigen. Kann das Dein Editor?
Weiß ich nicht und eigentlich ist mir das auch egal. Ich brauche kein "Syntax-Highlighting". Möglicherweise könnte ich Notepad++ manuell zwischen Perl und HTML umschalten.

Zitat
Das mit der Kurzreferenz finde ich einen guten Kompromiss.
Ich würde mal sagen, dass das sowieso der monentane Konsens ist.

Zitat
Beibt die Frage, was man unter Kurzreferenz versteht? Kannst Du es definieren?
Da hat man natürlich immer ein bisschen Interpretationsspielraum. Für mich heißt das, das alle Attribute, Readings, Sets und Gets aufgeführt sein sollten mit mindestens einem erklärenden Satz.

Zitat
Wie würdest Du die "Kleinigkeit" bzgl. dem commandref-Ungetüm denn lösen?
Das meinte ich gar nicht mit "einer Datei". Die Commandref wird sowieso aus vielen Dateien aufgebaut und wenn Du zur "modularen" Commandref umschaltest, dann siehst Du sie nicht mehr nur als ein großes Monster.
Ich meinte, dass man statt nur einer .pm mehrere Dateien für ein Modul haben könnte. Also z.B. eine .pm für das Coding, eine .en.html für die englische Commandref, eine .de.html für die deutsche Commandref etc.
Auf der anderen Seite ist das auch etwas Geschmacksache und IMHO nicht wirklich wichtig.

Gruß,
   Thorsten
FUIP

tupol

Zitat von: Thorsten Pferdekaemper am 18 März 2018, 16:18:37
Da hat man natürlich immer ein bisschen Interpretationsspielraum. Für mich heißt das, das alle Attribute, Readings, Sets und Gets aufgeführt sein sollten mit mindestens einem erklärenden Satz.
Das ist dann über nicht kurz sondern komplett. Insbesondere bei den Readings weichen da einige Module jetzt schon davon ab.
FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

tupol

Zitat von: Benni am 18 März 2018, 16:05:31
contrib wird nicht per update verteilt.
Damit macht man es dem Anwender aber dann tatsächlich schwer. :(
FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

Thorsten Pferdekaemper

Zitat von: tupol am 18 März 2018, 16:45:40
Das ist dann über nicht kurz sondern komplett.
Klar, so wie beim Linux "man". Es steht im Prinzip alles drin, aber ohne zu viel Blabla. Das ist insbesondere für denjenigen gedacht, der schon weiß, was das Ding macht, aber in Einzelfällen mal kurz nachschauen will.

Zitat
Insbesondere bei den Readings weichen da einige Module jetzt schon davon ab.
Das kann schon sein. Vielleicht ist nicht jeder meiner Meinung. ...oder es gibt Dinge, die sehr unwichtig sind, oder sowieso klar, oder...
Wie gesagt, es gibt da bestimmt einigen Interpretationsspielraum und man wird niemals alles formal vorschreiben können.

Gruß,
   Thorsten
FUIP

helmut

Zitat von: rudolfkoenig am 18 März 2018, 14:09:46
oder (was ich bevorzuge), schreibst die Umlaute in der HTML-Notation (ä Ä &szlig etc), womit dann alle zurechkommen.

Der Meinung bin ich auch. Der Einfachheit halber schreibe ich alle HTML-Dokumente mit dem vi mit Umlauten
hin und wenn ich fertig bin, wandle ich alles mittels eines vi-Makros, definiert in der .vimrc, einfach mit einem
CTRL-H in die HTML-konforme Schreibweise:

function HtmlUmlaute()
  silent %s/ä/\ä/eg
  silent %s/ö/\ö/eg
  silent %s/ü/\ü/eg
  silent %s/Ä/\Ä/eg
  silent %s/Ö/\Ö/eg
  silent %s/Ü/\Ü/eg
  silent %s/ß/\ß/eg
  silent %s/,,/\„/eg
  silent %s/"/\“/eg
  silent %s/–/\–/eg
  silent %s/é/\é/eg
endfunction
map <silent> <C-H> :call HtmlUmlaute()<CR>


Anschliessend pruefe ich die Dateien mit "tidy".
http://www.html-tidy.org/

Speziell zur commandref siehe auch tst-cmdref
https://forum.fhem.de/index.php/topic,84992.msg773003.html#msg773003

Zitat von: Thorsten Pferdekaemper am 18 März 2018, 17:00:41
Wie gesagt, es gibt da bestimmt einigen Interpretationsspielraum und man wird niemals alles formal vorschreiben können.

Die perfekte Doku gibt es auch bei kostenpflichtigen Produkten nicht. Meiner bescheidenen Meinung nach ist
die commandref (plus ergaenzendem WIKI) von fhem schon sehr gut. Sogenannte professionelle Erzeugnisse
sind in aller Regel nicht besser.

Gruss Helmut
Intelligenz ist die Fähigkeit, Arbeit zu vermeiden, aber dafür zu sorgen, daß die Arbeit gemacht wird.
(Linus Torvalds)

tupol

Wau. Das ist ja ein ganz schöner Aufwand, den Du da betreibst und ein gutes Beispiel, dass die beschriebenen Probleme mit HTML nicht nur bei mir vorkommen.
FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

helmut

Im Vergleich zu dem Aufwand der hinter dem Verlauf von der Idee ueber die Programmierung und
den Tests bis zur Fertigstellung eines Moduls und nicht zu vergessen, der Pflege steht, schaetze ich
diesen Teil als eher gering ein.

Wenn ich damit helfen kann, stelle ich mich gerne Dir und auch anderen zur Verfuegung, an
der Form Deiner/ihrer Modul-Doku mitzuarbeiten.

Gruss Helmut
Intelligenz ist die Fähigkeit, Arbeit zu vermeiden, aber dafür zu sorgen, daß die Arbeit gemacht wird.
(Linus Torvalds)