Pro: Argumente im Tag bei Prüfung durch commandref_join.pl

Ellert · 30 Dezember 2015, 17:46:30

Leider werden durch die Prüfung mit der neuen commandref_join.pl Tabellen in der Commandref unübersichtlicher. Ursache ist die vorgegebene vertikale Ausrichtung der Tabellenzeile auf zentriert. Das führt zu einer unübersichtlichen Darstellung, weil die Textabgrenzung zur vorhergehenden Zeile undeutlich ist.

Beispiel:

Text	Text Text Text
Text	Text Text Text

Es wäre nett, wenn das jemand hier http://forum.fhem.de/index.php/topic,46371.msg381299.html#msg381299 vorbringen könnte.

rudolfkoenig · 31 Dezember 2015, 10:05:16

Ich kann das Problem mit dem default style nicht nachvollziehen, vermutlich ist das Problem nur in einem der anderen Styles sichtbar.

Commandref sollte eine knappe aber praezise Dokumentation des Entwicklers sein, Nachschlagewerk fuer jemanden, der die Prinzipien verstanden hat, im Stil der Unix man-Pages. Deswegen sollte der Eintrag nur Text und keine/kaum Formatierung beinhalten, weil ich ein einheitliches Dokument haben will, was man auch auf einem Tablet oder Telefon noch lesen kann. Wenn manche Leute versuchen mit sehr viel Liebe zum Detail die Doku fuer ihr Modul schoen zu machen, leidet der Gesamteindruck darunter. Weiterhin kann ich bei dem extrem unterschiedlichen Know-How-Level und Sorgfalt der Beitragenden keinen einheitlichen Gesamteindruck gewaehrleisten. Also bitte, wenn irgendwie moeglich, auf Tabellen verzichten.

Bitte solche Beitraege nicht im Anfaengerfrage posten: Anfaenger interessiert das nicht, ich lese es nicht, und ein Entwickler sollte im Developer Bereich schreiben koennen. Wenn nicht, dann ist Sonstiges immer noch besser, als Anfaengerfragen.

Damian · 31 Dezember 2015, 11:55:17

Zitat von: rudolfkoenig am 31 Dezember 2015, 10:05:16
Ich kann das Problem mit dem default style nicht nachvollziehen, vermutlich ist das Problem nur in einem der anderen Styles sichtbar.

Commandref sollte eine knappe aber praezise Dokumentation des Entwicklers sein, Nachschlagewerk fuer jemanden, der die Prinzipien verstanden hat, im Stil der Unix man-Pages. Deswegen sollte der Eintrag nur Text und keine/kaum Formatierung beinhalten, weil ich ein einheitliches Dokument haben will, was man auch auf einem Tablet oder Telefon noch lesen kann. Wenn manche Leute versuchen mit sehr viel Liebe zum Detail die Doku fuer ihr Modul schoen zu machen, leidet der Gesamteindruck darunter. Weiterhin kann ich bei dem extrem unterschiedlichen Know-How-Level und Sorgfalt der Beitragenden keinen einheitlichen Gesamteindruck gewaehrleisten. Also bitte, wenn irgendwie moeglich, auf Tabellen verzichten.

Bitte solche Beitraege nicht im Anfaengerfrage posten: Anfaenger interessiert das nicht, ich lese es nicht, und ein Entwickler sollte im Developer Bereich schreiben koennen. Wenn nicht, dann ist Sonstiges immer noch besser, als Anfaengerfragen.

In dem Zusammenhang möchte ich noch mal die bereits angefangene Diskussion zu einzelnen Html-Pages pro Modul anregen.

Eine Html-Seite, die von Hunderten von Autoren erstellt wird, wird niemals einheitlich sein.

Eine präzise, verständliche aber auch ausführliche Doku (je nach Komplexität des Moduls) gehört meiner Meinung nach in die Commandref und nicht auf Wiki-Seiten, die von diversen Leuten erstellt werden, die z. T. die "Prinzipien" des jeweiligen Moduls nicht vollständig verstanden haben und umständliche Konstrukte beschreiben, weil sie es nicht besser wissen. Von der Aktualität der Beiträge, auf die man als Entwickler kaum Einfluss hat, will ich gar nicht sprechen. Das beste Beispiel ist der gut gemeinte Wiki-Beitrag zu DOIF, der längst überholt ist.

Gruß

Damian

marvin78 · 31 Dezember 2015, 12:06:13

Zitat von: Damian am 31 Dezember 2015, 11:55:17

Eine Html-Seite, die von Hunderten von Autoren erstellt wird, wird niemals einheitlich sein.

Warum eigentlich nicht? Wenn alles sich an die Vorgaben halten, ist das kein Problem. Eine komplett durchsuchbare commandref ist, meiner Ansicht nach, ohne Alternative.

Zitat von: Damian am 31 Dezember 2015, 11:55:17
Eine präzise, verständliche aber auch ausführliche Doku (je nach Komplexität des Moduls) gehört meiner Meinung nach in die Commandref und nicht auf Wiki-Seiten, die von diversen Leuten erstellt werden, die z. T. die "Prinzipien" des jeweiligen Moduls nicht vollständig verstanden haben und umständliche Konstrukte beschreiben, weil sie es nicht besser wissen. Von der Aktualität der Beiträge, auf die man als Entwickler kaum Einfluss hat, will ich gar nicht sprechen. Das beste Beispiel ist der gut gemeinte Wiki-Beitrag zu DOIF, der längst überholt ist.

Viele Beispiele, wie in deinem DOIF Modul, gehören nicht in eine commandref, sondern in ein Wiki. Einige wenige in der commandref reichen zur Veranschaulichung völlig aus (siehe readingsGroup). Es ist ja nicht ausgeschlossen, dass jeder Modulautor für solche Fälle einen Wiki-Artikel pflegt und in der commandref auf diesen verlinkt. Es reicht völlig aus, wenn in der commandref die Definition, die Funktion und die Konfiguration des Moduls klar und präzise beschrieben wird. Falls es weiterer Erklärung bedarf (die dann ggf. auch formatiert sein muss) gehört das, meiner Ansicht nach, in das Wiki. Mehr Arbeit für den Modulautor ist das nicht zwingend. Ich möchte in einer commandref die klare und knappe Beschreibung des Moduls sehen. Alles weitere ist mir zu viel.

Amenophis86 · 31 Dezember 2015, 17:12:15

Zitat von: marvin78 am 31 Dezember 2015, 12:06:13
(siehe readingsGroup)

Gerade das ist ein Beispiel, welches ich nicht gut finde. Ich hatte als Anfänger SEHR mit readingsGroup zu kämpfen, da es mir nicht ganz verständlich war. Im Wiki stand dann nur "siehe CommandRef" das hat null geholfen. Natürlich kann man hier im Board sich die Antworten dann auch zusammen suchen. Dies hat bei mir ja auch immer zur Lösung geführt, aber einfach war es nicht.

Ich bin eher dafür, dass das Wiki von den Modul-Erstellern besser gepflegt wird, wodurch die CommandRef auf weniges beschränkt werden kann. Natürlich ist das mehr Arbeit für den Entwickler, aber für die User wesentlich besser. Aktuell ist es so, dass das Wiki oft hinterher hängt und die CommandRef kurz gehalten ist. Dann kommt noch dazu, dass manche nur die Englische CommandRef bedienen und die deutsche vernachlässigen. Was ja klar ist, da die Englische Pflicht und die Deutsche ein kann ist.

Ich würde mir somit wünschen, dass die Entwickler mehr am Wiki Arbeiten und damit die CommandRef kurz halten können. Das Wiki ist eine gute Alternative, welche alle gestalterischen Möglichkeiten offen lässt.

Über das Design der Commandref kann man sich streiten. Ich denke, dass zB auch ein paar Tabellen Linien das Lesen einfach machen würden, da man eher sieht wo etwas anfängt bzw aufhört. Über die Suche findet man manchmal einen Begriff und muss dann beim Scrollen nach oben aufpassen, dass man den Modulnamen nicht verpasst. Da würden zB Linien helfen.

justme1968 · 31 Dezember 2015, 20:33:20

ich glaube es gibt keine wiki seite mit mehr beispielen als die zur readingsGroup.

wenn dir hier etwas fehlt: es steht jedem frei mitzumachen und das wiki zu ergänzen.

die commandref ist für screenshots wie sie für readingsGroup beispiele nötig sind definitiv nicht der richtige ort.

gruss
andre

Wuppi68 · 31 Dezember 2015, 23:09:06

wenn wir schon einmal bei der Commandref sind

ich hätte da gerne eine einheitliche Syntaxdefinition für die Commandzeile ..

so in der Art:

define <Unique Identifier> IRGENDEINMODUL <Regel1 | Regel2> Parameter1 <Parameter2> <Parameter..n>

also im Prinzip das was der Parser entsprechend auswertet.

Gerade bei einem so komplexen Modul wie DOIF würde das ein wenig die "Kurzreferenz" vereinfachen

Amenophis86 · 01 Januar 2016, 10:07:13

Zitat von: justme1968 am 31 Dezember 2015, 20:33:20
ich glaube es gibt keine wiki seite mit mehr beispielen als die zur readingsGroup.

Du hast recht, muss mich korrigieren. Ich meinte structure. Sry

krikan · 01 Januar 2016, 10:13:56

Zitat von: Amenophis86 am 01 Januar 2016, 10:07:13
Du hast recht, muss mich korrigieren. Ich meinte structure. Sry

Dann kannst Du das jetzt als Fortgeschrittener gerne im Wiki erläutern/ergänzen, damit die nachfolgenden Einsteiger es einfacher haben. Wenn Du noch nicht angemeldet bist, geht es hier entlang: http://www.fhemwiki.de/wiki/FHEMWiki:Administratoren

Gruß, Christian

Amenophis86 · 01 Januar 2016, 10:56:21

Schau an, dachte das wäre Entwicklern vorbehalten. Dann werde ich das die Tage mal machen. Vielen Dank für die Info.

rudolfkoenig · 01 Januar 2016, 11:22:38

ZitatNatürlich ist das mehr Arbeit für den Entwickler, aber für die User wesentlich besser.

Bitte mit sochen Aussagen vorsichtig sein, Entwickler ist ein scheues Wild.

Ich kann gut verstehen, dass ein Benutzer eine detaillierte Dokumentation wuenscht, am besten mit Beispielen fuer genau seinen Fall, die man nur per Copy&Paste einsetzen muss, womoeglich mit Beratung und Debugging vorort.

Ich vertrete den Entwickler, der nach Arbeit in seiner Freizeit etwas fuer sich bastelt, und weil er den Anderen, die zu FHEM beigetragen haben, was zurueckgeben will, sein Gewerk noch dokumentieren muss. Ich werde die Huerde sicher nicht weiter heben, da ich mich freue, wenn seine Arbeit nicht irgendwo verschwindet. Der Besagte kriegt eh einen Schock, wenn er feststellt, dass sein Modul den Nerv der Zeit trifft, und er ploetzlich dutzende oder gar hunderte Fragen beantworten muss, oder Verbesserungsvorschlaege impementieren darf, die fuer ihn selbst vollkommen irrelevant sind, und damit er unter dem Strich zu viel fuer FHEM "bezahlt" hat.

Es gibt viele Leute, die nicht programmieren koennen oder wollen. Wieso teilen wir die Arbeit nicht auf?
Commandref liefert der Entwickler, und das ist zwar vollstaendig aber knapp. Im Wiki kann (soll?) jeder mitmachen, und da ist viel Platz fuer Geschichten, Bilder, Copy&Paste Beispielen und fertige HOWTOs.

Ein anderes Aspekt, was Einsteiger gerne uebersehen: einen erfahrenen Anwender/Entwickler nervt eine lange und detaillierte Doku, so aehnlich wie wenn Erwachsene Kinderbuecher lesen. Das ist keine Ueberheblichkeit, er hat nur bisher 1000-mal mehr Zeit mit der Materie verbracht als ein Anfaenger, und er braucht viele Basics nicht mehr. Wenn wir das Commandref aufblasen, dann nehmen wir anderen Entwicklern die verstaendliche und effiziente Doku weg.

Damian · 01 Januar 2016, 13:40:49

Zitat von: rudolfkoenig am 01 Januar 2016, 11:22:38
Bitte mit sochen Aussagen vorsichtig sein, Entwickler ist ein scheues Wild.

Ich kann gut verstehen, dass ein Benutzer eine detaillierte Dokumentation wuenscht, am besten mit Beispielen fuer genau seinen Fall, die man nur per Copy&Paste einsetzen muss, womoeglich mit Beratung und Debugging vorort.

Ich vertrete den Entwickler, der nach Arbeit in seiner Freizeit etwas fuer sich bastelt, und weil er den Anderen, die zu FHEM beigetragen haben, was zurueckgeben will, sein Gewerk noch dokumentieren muss. Ich werde die Huerde sicher nicht weiter heben, da ich mich freue, wenn seine Arbeit nicht irgendwo verschwindet. Der Besagte kriegt eh einen Schock, wenn er feststellt, dass sein Modul den Nerv der Zeit trifft, und er ploetzlich dutzende oder gar hunderte Fragen beantworten muss, oder Verbesserungsvorschlaege impementieren darf, die fuer ihn selbst vollkommen irrelevant sind, und damit er unter dem Strich zu viel fuer FHEM "bezahlt" hat.

Es gibt viele Leute, die nicht programmieren koennen oder wollen. Wieso teilen wir die Arbeit nicht auf?
Commandref liefert der Entwickler, und das ist zwar vollstaendig aber knapp. Im Wiki kann (soll?) jeder mitmachen, und da ist viel Platz fuer Geschichten, Bilder, Copy&Paste Beispielen und fertige HOWTOs.

Ein anderes Aspekt, was Einsteiger gerne uebersehen: einen erfahrenen Anwender/Entwickler nervt eine lange und detaillierte Doku, so aehnlich wie wenn Erwachsene Kinderbuecher lesen. Das ist keine Ueberheblichkeit, er hat nur bisher 1000-mal mehr Zeit mit der Materie verbracht als ein Anfaenger, und er braucht viele Basics nicht mehr. Wenn wir das Commandref aufblasen, dann nehmen wir anderen Entwicklern die verstaendliche und effiziente Doku weg.

So ist das wohl, allerdings ist "vollstaendig aber knapp" relativ zu sehen. Bei einem notify-Kommando oder at-Kommando mag "knapp" mit einigen Zeilen realisierbar zu sein. Bei komplexeren Modulen hat bei "vollstaendig" das Wort "knapp" eine andere Dimension. Die Beispiele, die z. B. in der Commandref des DOIF-Moduls vorkommen, sind nicht zufällig ausgewählt, sondern sind kleine "Killerapplikationen" die bestimme Features des Moduls schnell transparent machen. Sie sind für diesen Zweck von mir sehr sorgfältig ausgewählt worden. Diese Beispiele möchte ich z. B. nicht ins Wiki stellen, denn ich möchte die Kontrolle über diese behalten. Bei DOIF gibt es sehr viele Wege etwas umzusetzen und genauso gibt auch sehr viele Wege, die nicht nur umständlich, sondern kontraproduktiv irgendwo im Forum oder im Wiki beschrieben sind, auch wenn sie funktionieren. Diese darf man dann als Entwickler hier im Forum wieder gerade stellen.

Ich habe nichts dagegen, wenn User Wiki-Einträge produzieren, die über den Standard hinausgehen, die durchaus sinnvoll sein können, wenn sie sich mit dem jeweiligen Modul gut auskennen.

Ich plane für dieses Jahr ein DOIF-Anwenderhandbuch, welches ich nicht in die Commandref aber auch nicht ins Wiki stellen werde.

Gruß

Damian

rudolfkoenig · 01 Januar 2016, 14:06:47

DOIF ist aus mehreren Gruenden kein gutes Beispiel fuer Commandref Eintraege, die wichtigsten sind mAn, dass die Zielgruppe von DOIF keine Entwickler sind, und dass der Commandref nicht fuer Beschreibung von Programmiersprachen gedacht ist. Ich wuerde eine Doku mit solchen Inhalt eher im Wiki oder als PDF erwarten.

herrmannj · 01 Januar 2016, 14:15:44

ich finde die DOIF Beispiele in der cmdref gut - ich verstehe damit schnell worum es geht, kann die schnell adaptieren. Da würde ich auch nicht erst im wiki suchen wollen. Meine Meinung daher: sollte so bleiben, sogar ausgebaut.

vg
joerg

marvin78 · 01 Januar 2016, 14:23:00

Und mich machen die vielen Beispiele wahnsinnig und ich bin froh dass sie in der englischen Variante nicht vorhanden sind. Eine klare Doku und dann meinetwegen ein Verweis auf Beispiele in einem Wiki wären für mich perfekt. So hat jeder seine Vorlieben. Ich halte Rudis Argumentation für sehr gut nachvollziehbar und schlüssig. Seine Vorstellung von einer commandref gefällt mir.

Von einem weiteren Dokument als Hilfe für ein (zugegeben komplexes) Modul, halte ich jedoch nichts. Warum auch, wenn man doch ein Wiki hat? Das führt zum einen einige der Argumente hier ad absurdum und zum anderen erleichtert es den Supoort sicher auch nicht.