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.
Siehe hier:
https://forum.fhem.de/index.php?topic=85258.new;topicseen#new (https://forum.fhem.de/index.php?topic=85258.new;topicseen#new)
Zitat von: Dr. Boris Neubert am 18 März 2018, 11:28:42
Siehe hier:
https://forum.fhem.de/index.php?topic=85258.new;topicseen#new (https://forum.fhem.de/index.php?topic=85258.new;topicseen#new)
Da steht etwas über die Wiki-Anleitungen für Entwickler. Welchen Bezug siehst Du zu dem obigen Thema?
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
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.
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.
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.
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
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.
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
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?
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 (ä Ä ß etc), womit dann alle zurechkommen. Ja, die Nachteile sind mir auch bekannt.
OK. Das war der Fehler.
@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?
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.
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
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.
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. :(
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
Zitat von: rudolfkoenig am 18 März 2018, 14:09:46
oder (was ich bevorzuge), schreibst die Umlaute in der HTML-Notation (ä Ä ß 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?action=dlattach;topic=84992.0;attach=97218)
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
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.
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