Umgang mit Widersprüchen zwischen CommandRef, Wiki und dem Rest des Internets

Begonnen von Dr. Boris Neubert, 30 Januar 2018, 06:57:03

Vorheriges Thema - Nächstes Thema

Dr. Boris Neubert

Hallo,

letzte Woche wurde ein Anwender von FHEM unglücklich, weil er den Anweisungen im Wiki gefolgt ist statt der CommandRef. Es ist ein grundsätzliches Problem, dass sich die Module und Betriebssysteme/Distributionen weiterentwickeln und die Informationen im Wiki, in Forenartikeln und auf anderen Webseiten veralten und manche heutzutage nicht mehr so funktionieren, wie es zum Zeitpunkt der Erstellung der Fall war (konkreter Fall: https://wiki.fhem.de/wiki/OWServer_%26_OWDevice).

Als Entwickler investiere ich Arbeit in die Dokumentation in der CommandRef, damit jeder grundsätzlich Sachkundige damit ein Modul in Betrieb nehmen kann. Dabei gehe ich auch auf Sonderfälle und Probleme ein. Ich bin aber nicht imstande, gleichzeitig auch noch das Wiki zu pflegen. Bei alten Forenbeiträgen oder dem Rest des Internets ist das ganz und gar unmöglich.

Neben der Hoffnung, dass freundliche Helfer das Wiki auf den Stand bringen, schlage ich vor, dass wir im Forum, im Wiki und in der CommandRef eine Vorfahrtsregel etablieren und aktiv bekannt machen, dass nämlich die CommandRef vorgeht und bei Widersprüchen das richtig ist, was in der CommandRef steht.

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

marvin78

Das ist etwas, das viele Helfer hier seit Jahren runter beten, wenn es  zu ähnlichen Problemen kommt (und das ist nicht selten der Fall). Eine prominent platzierte Regel würde ich begrüßen.

darkness

Gibt es denn eine Möglichkeit Änderungen in der CommandRef kenntlich zu machen? Somit wäre es für Wiki-Autoren einfacher die Änderungen zu übernehmen.
Alternativ kann man ja neben dem Modulautor auch einen Doku-Verantwortlichen nennen. Dieser könnte dann in Abstimmung mit dem Modulautor die Pflege des Wikis übernehemen.

Aber mal davon abgesehen. Es heißt doch immer, dass die CommandRef die "offizielle" Doku ist. Alles andere ist ja mehr Unterstützung.


CoolTux

Zitat von: darkness am 30 Januar 2018, 07:07:31
Aber mal davon abgesehen. Es heißt doch immer, dass die CommandRef die "offizielle" Doku ist. Alles andere ist ja mehr Unterstützung.

Naja und nun muss es halt nur noch irgendwo platziert werden wo jeder es lesen kann sofern er will.
Im Anfänger PDF und im Anfänger Forum oben gepinnt.
Du musst nicht wissen wie es geht! Du musst nur wissen wo es steht, wie es geht.
Support me to buy new test hardware for development: https://www.paypal.com/paypalme/MOldenburg
My FHEM Git: https://git.cooltux.net/FHEM/
Das TuxNet Wiki:
https://www.cooltux.net

CBSnake

Moin,

und evtl noch als Standardsatz zwischen Inhaltsverzeichnis und erstem Absatz das jeweiligen Wiki-Artikel ;-)

Grüße
Achim
FHEM auf Debian 10, HM-Wlan, JeeLink-Wlan, Wlanduino, ConBee, TP-Link Steckdose, GHoma Steckdosen, Shelly Steckdosen

krikan

Eigentlich wollte ich mit der Box "Was ist FHEM Wiki" auf https://wiki.fhem.de/wiki/Hauptseite und dem Satz dort "Das FHEM Wiki ergänzt die stets tagesaktuelle, von den zuständigen Entwicklern gepflegte commandref (Befehls-Referenz) um weitergehende Informationen rund um FHEM." sowie den folgenden Infos genau auf den Vorrang der commandref hinweisen. Ich nehme grundsätzlich gerne Verbesserungsvorschläge an. Ich könnte das beispielsweise noch um vorrangige hinter "tagesaktuell" ergänzen.

Letztlich zweifel ich aber ein wenig am Erfolg weiterer Erläuterungen. Denn: wer liest das? Wir werden immer wieder Probleme haben, dass irgendwer mit irgendwelchen veralteten oder fehlerhaften Infos aus dem Wiki oder gar den Weiten des Internets hier aufschlägt und nachfragt statt zunächst in der commandref nachzuschauen.

@Boris: Verlinkst Du mir bitte den Problem-Thread zu https://wiki.fhem.de/wiki/OWServer_%26_OWDevice oder ist die Seite komplett überholt?

Gruß, Christian

Intruder1956

guten morgen,
meine Gedanken bei Lesen dieses Thread  ;)
das Problem wird aber sein, das in der CommandRef nicht alle Module oder Hilfsprogramme auf Deutsch sind.
Solche ungebildeten alten User wie mir macht es dann Probleme den englischen Text zu verstehen und komme keinen Schritt weiter.
Daher sucht man dann im Wiki oder im Internet nach Möglichkeiten, das Modul oder Hilfsprogramm zu verstehen,
bzw. zu schauen was kann es, wofür kann ich es nutzen, brauche ich es, oder kann es mir die Spielerei vereinfachen  ;)
Es ist mir schon passiert, das ich ein Hilfsmodul nutzen wollte, es nicht geklappt hat. Ich das Forum durchwühlt habe.
Mich dabei über Stunden durch 70 Seiten gelesen habe, alles ausprobiert habe was von Anfang bis Ende dieses ForumThread angeboten wurde,
und ich letztendlich immer noch kein richtiges Ergebnis hatte
Viele Grüße

Werner
 
Zotac CI547 32GB RAM 500GB SSD,ESXI 6.5, VM-Fhem5.8, VM-ioBroker, Cul 868Mhz;Cul 433Mhz = Busware, LGW, HM-MOD-RPI-PCB, Uniroll, IT YCR-100 TMT2100,ITR-1500, LD382 mit Wifilight, ESA 2000 + SENSOR WZ SET,FS20 TFK, HM-Sec-SC, HM-CC-RT-DN,PCA301,

marvin78

Die, die nicht erst in der commandref nachschauen, sind zwar ärgerlich, aber nicht das Problem. Es sind die, die auch nach mehrmaligem Hinweisen, dass die commandref die Doku ist und nicht das Wiki, noch darauf bestehen, dass im Wiki gefälligst alles korrekt sein solle und der Entwickler des/der Moduls/e das auch gefälligst zu pflegen hat. Viele erwarten tatsächlich unsinnigerweise, dass sich hinter einem "Wiki" alle Weisheit versteckt. Ich glaube auch, dass ein Hinweis nicht gelesen wird, wenn es aber offiziell und prominent (und zwar nicht im Wiki, denn wir wollen ja klar machen, dass dort nicht immer die ganze "Wahrheit" steht ;)), zu lesen ist, kann man als Helfer darauf hinweisen und ellenlange Diskussionen um das Thema ggf. schneller beenden.

Dass die commandref nicht immer auf deutsch ist, ist ganz sicher nicht das Problem für die Allgemeinheit. Ich denke, wenn jemand (und das sind wenige Einzelfälle) in seinen Fragen klar und deutlich darauf hinweist, dass er überhaupt nicht in der Lage ist, den englischen Text zu verstehen, macht das keine Probleme. Ich behaupte auch, dass man nur mit der commandref weit über 95% aller offiziellen Module zufriedenstellend ans Laufen bekommt. Ich wiederhole es gerne: Wer das nicht schafft, hat bei FHEM nicht viel verloren.

Aber das soll hier sicher keine Diskussion von commandref vs. Wiki oder englisch vs. deutsch werden. Es geht nur im die Regeln und den entsprechenden Hinweis.

Dr. Boris Neubert

Zitat von: krikan am 30 Januar 2018, 08:34:11
@Boris: Verlinkst Du mir bitte den Problem-Thread zu https://wiki.fhem.de/wiki/OWServer_%26_OWDevice oder ist die Seite komplett überholt?

https://forum.fhem.de/index.php/topic,83120.msg757737.html#msg757737

Für Debian Jessie sind die Installationshinweise vermutlich noch zutreffend, für Stretch nicht mehr.

Das Problem an Doku ist, dass der Anwender sie lesen muss. Um sie zu lesen, muss er sie finden/wissen, dass es sie gibt. In dem angeführten Thread ist der Anwender per Websuche ins Wiki gestürzt und war nicht mit der Dokumentationsarchitektur von FHEM vertraut.

Vermutlich ist es schon förderlich, bei jedem Wiki-Artikel zu Modulen bereits im Template vorzusehen, dass klar und deutlich darin steht, dass die commandRef die aktuelle Dokumentation ist, ggf. versehen mit dem Hinweis, auch auf das Datum in der Fußzeile und das letzte Änderungsdatum des Moduls und dessen Änderunghistorie zu achten bei der Einschätzung, wie zutreffend die Einträge noch sind.

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

nils_

Zitat von: darkness am 30 Januar 2018, 07:07:31
Gibt es denn eine Möglichkeit Änderungen in der CommandRef kenntlich zu machen? Somit wäre es für Wiki-Autoren einfacher die Änderungen zu übernehmen.
Alternativ kann man ja neben dem Modulautor auch einen Doku-Verantwortlichen nennen. Dieser könnte dann in Abstimmung mit dem Modulautor die Pflege des Wikis übernehemen.
momentan siehst du Änderungen nur durch ein ändernung der Modul-Datei (nicht zwingend dann der cref anteil am ende!)

man könnte ja sowas hier einbauen https://wuhrr.wordpress.com/2010/03/30/automate-email-notifications-for-subversion-svn-commits/
und damit dann evtl. wiki-verantwortliche per eMail zu informieren das sich etwas geändert hat.
pflegeaufwand dafür (wer für welches modul wiki einträge erstellt usw.) kann ich momentan nicht einschätzen.
viele Wege in FHEM es gibt!

LuckyDay

Kann es sein dass fhem sich nicht lokal an localhost mehr binden kann?
kann ja auch nicht sein, dass man owfs , das Scheunentor für alle öffnen muss.

laut doku owfs, ist --> server: port = localhost:4304 , durchaus aktuell.

Dr. Boris Neubert

Zitat von: nils_ am 30 Januar 2018, 09:38:25
evtl. wiki-verantwortliche

Wenn wir Enthusiasten finden, die bestimmte Artikel oder Wiki-Bereiche unter ihre Fittiche nähmen, wäre das ideal. Bei den Übersetzungen der CommandRef ins Deutsche gab es ja eine Reihe Helfer.
Globaler Moderator, Developer, aktives Mitglied des FHEM e.V. (Marketing, Verwaltung)
Bitte keine unaufgeforderten privaten Nachrichten!

CoolTux

Zitat von: fhem-hm-knecht am 30 Januar 2018, 09:51:13
Kann es sein dass fhem sich nicht lokal an localhost mehr binden kann?
kann ja auch nicht sein, dass man owfs , das Scheunentor für alle öffnen muss.

laut doku owfs, ist --> server: port = localhost:4304 , durchaus aktuell.

Falscher Thread. Hier geht es nicht um owfs
Du musst nicht wissen wie es geht! Du musst nur wissen wo es steht, wie es geht.
Support me to buy new test hardware for development: https://www.paypal.com/paypalme/MOldenburg
My FHEM Git: https://git.cooltux.net/FHEM/
Das TuxNet Wiki:
https://www.cooltux.net

nils_

Zitat von: Dr. Boris Neubert am 30 Januar 2018, 09:52:14
Bei den Übersetzungen der CommandRef ins Deutsche gab es ja eine Reihe Helfer.
für die Übersetzungshelfer wäre eine Benachrichtigung bei änderungen am englischen Teil natürlich auch interessant (wenn derjenige das natürlich weiterbetreuen möchte).
unschön wird es natürlich wenn der englische und deutsche teil komplett auseinanderlaufen.
Klar sollte aber auch sein, das es vom modulautor verpflichtend nur den commandref anteil gibt. Wiki o.ä. sind nur Beiwerk, oder von anderen geschrieben!


grundsätzlich finde ich eine automatische benachrichtigung bei änderungen an modulen interessant, ob es dann ein übersetzungshelfer, wiki-verantwortlicher, blog-schreiber, modul-benutzer, .... ist unerheblich.
viele Wege in FHEM es gibt!

Dr. Boris Neubert

Zitat von: nils_ am 30 Januar 2018, 10:09:13
grundsätzlich finde ich eine automatische benachrichtigung bei änderungen an modulen interessant, ob es dann ein übersetzungshelfer, wiki-verantwortlicher, blog-schreiber, modul-benutzer, .... ist unerheblich.

Wir hatten mal die Commit Messages aus dem Repo in ein Board gestreamt. Zusammen mit E-Mail-Benachrichtungen und einem Filter (einfach, weil alle Commit Messages den Namen des Moduls beinhalten) wäre das schon die Lösung gewesen. Aber das scheint es nicht mehr zu geben.
Globaler Moderator, Developer, aktives Mitglied des FHEM e.V. (Marketing, Verwaltung)
Bitte keine unaufgeforderten privaten Nachrichten!

nils_

viele Wege in FHEM es gibt!

Dr. Boris Neubert

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

Beta-User

Wenn ich nochmal zurückkommen darf auf
Zitat von: krikan am 30 Januar 2018, 08:34:11
Eigentlich wollte ich mit der Box "Was ist FHEM Wiki" auf https://wiki.fhem.de/wiki/Hauptseite und dem Satz dort "Das FHEM Wiki ergänzt die stets tagesaktuelle, von den zuständigen Entwicklern gepflegte commandref (Befehls-Referenz) um weitergehende Informationen rund um FHEM." sowie den folgenden Infos genau auf den Vorrang der commandref hinweisen. Ich nehme grundsätzlich gerne Verbesserungsvorschläge an. Ich könnte das beispielsweise noch um vorrangige hinter "tagesaktuell" ergänzen.

Letztlich zweifel ich aber ein wenig am Erfolg weiterer Erläuterungen. Denn: wer liest das? Wir werden immer wieder Probleme haben, dass irgendwer mit irgendwelchen veralteten oder fehlerhaften Infos aus dem Wiki oder gar den Weiten des Internets hier aufschlägt und nachfragt statt zunächst in der commandref nachzuschauen.
Auch wenn ich die Skepsis hinsichtlich der Breitenwirkung entsprechender Klarstellungen mittlerweile teile:

Mir kommt es immer noch so vor, dass die überwiegende Mehrzahl der User nicht weiß oder hartnäckig verdrängt, dass die (englische!) Commandref die einzige verpflichtende Doku für Entwickler ist. Alles andere (wie auch eine Qualitätskontrolle für neu eingecheckte Module) ist freiwillig. Das hat sich bewährt, nur ist es eben (zu?) vielen (Einsteigern?) nicht klar. Dazu kommt, dass es auch keine wirkliche Qualitätskontrolle für Wiki-Artikel gibt. Auch das ist an sich ok (sonst würde es vermutlich deutlich weniger durchaus hilfreiche Beiträge geben), beinhaltet aber auch das Risiko, dass gerade Neulinge glauben, diese "zweit- oder drittbeste" Doku sei die "beste". Und ob Hinweisautomatismen an Wiki-Autoren wirklich helfen, wage ich zu bezweifeln, da die Wiki-Themen in der Regel doch eher statisch sind und Probleme oft erst entstehen, wenn sich was im Umfeld ändert (jessie->stretch). Das muß nicht zwingend heißen, dass ein Modul zu überarbeiten ist...

Bislang steht afaik aber an keiner prominenten Stelle, wie sich das Dokumentationspuzzle wirklich zusammensetzt bzw. wie es zu verstehen/zu durchforsten ist.

Konkret hätte ich folgenden Vorschlag:

Den Satz
ZitatDas FHEMWiki stellt neben der commandref, dem Forum und der FHEM Seite die zentrale Informationsquelle rund um FHEM dar.
ersetzen durch einen Link auf einen eigenen Wiki-Artikel, der z.B. mit "Struktur der Informationsquellen zu FHEM" überschrieben sein könnte.

Darin könnte dann stehen:
1. commandref
Die für die an der Entwicklung von FHEM beteiligten Softwareentwickler (Modulautoren) allein verpflichtende Ort für eine Dokumentation ist eine englische Commandref. (Diese sollte so gestaltet sein, dass mit dieser das betreffende Modul eingerichtet werden kann).
Alle FHEM-Anwender sollten daher zunächst in der commandref nachsehen, wie Module oder FHEM-Befehle einzusetzen sind bzw. nach Lösungsansätzen für ihre Fragestellungen suchen. Auch neue Funktionen usw. werden hier von den Modulautoren tagesaktuell dokumentiert.

2. FHEM.de
Allgemeines zum FHEM sowie Installationsanleitungen.

3. a. Wiki
Die Artikel im Wiki stammen teilweise von den Modulautoren selbst, in der Regel werden diese jedoch von Anwendern für andere Anwender erstellt. Dementsprechend ist die Aktualität und Qualität der Artikel unterschiedlich. Für Verbesserungsvorschläge zum Wiki besteht ein eigener Bereich im Forum (https://forum.fhem.de/index.php/board,80.0.html).

3. b. Forum
Im Forum stellen manche Entwickler, insbesondere auch solche (noch) inoffizieller Module, weitere Informationen zur Verfügung. Nützliche Infos zum Forum selbst sind hier zu finden (sticky Threads im Anfängerbereich und evtl. nochmals speziell: wie suche ich?).

Wäre sicher noch auszubauen, aber so in der Art halt...

Wie meistens: Just my2ct.

Beta-User
Server: HP-elitedesk@Debian 12, aktuelles FHEM@ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

Dr. Boris Neubert

Hi Beta-User,

finde ich gut (siehe Stichwort Dokumentationsarchitektur).

Für alle, die nicht gerne klicken und lesen, sollte zusätzlich der Hinweis erhalten bleiben, dass, wenn es Dokumentation gibt, die ultimative Wahrheit in der englischen CommandRef liegt (ich pflege auch die deutsche CommandRef in meinen Modulen, weil das sonst nie mehr jemand zusammenbekäme, und das sollte für alle Entwickler verpflichtend sein, die auch eine deutsche CommandRef haben). Und diesen Hinweis würde ich gleichlautend überall hinnageln. Ich teile Deine Skepsis hinsichtlich der Breitenwirkung entsprechender Klarstellungen, aber hier hilft die Wiederholung zumindest die Quote zu erhöhen.

Grüße
Boris

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

krikan

Hallo Beta-User!

ZitatKonkret hätte ich folgenden Vorschlag

Du kannst das gerne direkt ins Wiki einbauen. Dann können wir gemeinsam dort direkt daran arbeiten.

Gruß, Christian

nils_

@Beta-User:

ich finde die idee gut!
evtl. solltest du noch erwähnen das es auch außerhalb von fhem blogs gibt, und bei diesen sollte noch mehr auf den stand der informationen geachtet werden. da ja immer wieder fragen zu _alten_ versionen im forum aufschlagen.


kurzer ausflug noch @ boris, da wir ja das forum wiedergefunden haben :)
Zitat von: Dr. Boris Neubert am 30 Januar 2018, 10:21:57
... einfach, weil alle Commit Messages den Namen des Moduls beinhalten...
ist das wirklich so? es gibt u.U. auch schonmal commits die mehrere module betreffen.
ein automatismus der sich jedes modul ansieht bzgl. änderungen und dann eMails verschickt wäre etwas umfassender.

aber das soll es auch zu diesem thema gewesen sein, oder wir verlagern das in einen anderen thread :)
das forum mit den code changes ist zumindest schonmal ein ansatzpunkt für interessierte ;)



//edit:
ein aktuelles beispiel für commandref != wiki
https://forum.fhem.de/index.php/topic,83584.0.html
viele Wege in FHEM es gibt!

Beta-User

Danke für die positiven Rückmeldungen.

Die erste Fassung zur Dokumentationsstruktur (einschl. Hinweis auf die zweifelhafte Qualität von Blogs etc.) ist hier zu finden: https://wiki.fhem.de/wiki/Dokumentationsstruktur

Wenn das soweit in berufenen Augen ok ist, würde ich das dann noch auf der Hauptseite entsprechend verlinken (bzw. gerne auch jemand anderes...).

Gruß, Beta-User
Server: HP-elitedesk@Debian 12, aktuelles FHEM@ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

Amenophis86

Ich möchte nochmals meinen Vorschlag unterbreiten, dass wir hier in FHEM ansetzen sollten und nicht im Forum. Zum Beispiel könnte man über ein News-Device auch Nachrichten verteilen, wie die oben rechts im Forum. Auch bei der erst Installation sollte nicht nur der Hinweis auf allowed erscheinen, sondern vielleicht ein Hinweis auf die CommandRef, das Wiki und das Forum mit entsprechender Priorisierung etc.

Ja, mir ist klar, dass es auch Installationen ohne Internet gibt, aber der größte Teil dürfte aufs Internet zugreifen können.
Aktuell dabei unser neues Haus mit KNX am einrichten. Im nächsten Schritt dann KNX mit FHEM verbinden. Allein zwei Dinge sind dabei selten: Zeit und Geld...

Benni

Zitat von: Beta-User am 30 Januar 2018, 11:16:55

Wenn das soweit in berufenen Augen ok ist, würde ich das dann noch auf der Hauptseite entsprechend verlinken (bzw. gerne auch jemand anderes...).

Gruß, Beta-User

Das gehört dann aber eigentlich so auch auf die fhem.de - Hauptseite unter "Documentation"

Apropos: Wenn du fhem.de schon in der Auflistung mit drin hast, gehört das m.E. an die erste Stelle.

Dr. Boris Neubert

Zitat von: Amenophis86 am 30 Januar 2018, 11:26:58
Ich möchte nochmals meinen Vorschlag unterbreiten, dass wir hier in FHEM ansetzen sollten und nicht im Forum. Zum Beispiel könnte man über ein News-Device auch Nachrichten verteilen, wie die oben rechts im Forum. Auch bei der erst Installation sollte nicht nur der Hinweis auf allowed erscheinen, sondern vielleicht ein Hinweis auf die CommandRef, das Wiki und das Forum mit entsprechender Priorisierung etc.

Ja, mir ist klar, dass es auch Installationen ohne Internet gibt, aber der größte Teil dürfte aufs Internet zugreifen können.

Martin hatte ein Messaging-System für FHEM entwickelt. Das hat den Anwender teilweise gezwungen, vor/nach dem Update Hinweise abzunicken. Irgendwann ist es dann rausgeflogen. Ich weiß aber nicht, warum. Das könnte man reaktivieren.
Globaler Moderator, Developer, aktives Mitglied des FHEM e.V. (Marketing, Verwaltung)
Bitte keine unaufgeforderten privaten Nachrichten!

Beta-User

Zitat von: Benni am 30 Januar 2018, 11:28:20
Apropos: Wenn du fhem.de schon in der Auflistung mit drin hast, gehört das m.E. an die erste Stelle.
Agreed und erledigt.

Zitat von: Benni am 30 Januar 2018, 11:28:20
Das gehört dann aber eigentlich so auch auf die fhem.de - Hauptseite unter "Documentation"
Das mögen andere entscheiden, die sehr übersichtliche und schlanke Seite sollte man m.E. auch nicht zu sehr aufbohren. Zur Diskussion möchte ich aber noch den Gedanken geben, die Bedeutung der CommandRef an der Stelle nochmal zu unterstreichen. In die Richtung: "If you are looking for accurate and up-to-date documentation, this is the place to start with!".

Server: HP-elitedesk@Debian 12, aktuelles FHEM@ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

rudolfkoenig

ZitatIrgendwann ist es dann rausgeflogen. Ich weiß aber nicht, warum.
Weil ich irgendwannmal ausgerastet bin, nachdem ich den komplizierten Abnick-Mechanismus nach jeder Neuinstallation + update ausfuehren musste. Und wir hatten Jahre lang nur eine einzige Nachricht im System, wehe, wenn das System ernst genommen wird, und jeder Entwickler einstellen kann, dass Attribut X ab morgen Y genannt wird. Ist auch eine einseitige Kommunikation, da der Anwender nichts sagen kann.
Uebrigens:
- FHEM/98_notice.pm gibts immer noch, wird nur nicht mehr nach update aufgerufen.
- ein HTML Frontend zum Abnicken bei notice gibt es mW nicht.

Wir haben CHANGED, commandref, forum, wiki, EinsteigerDoku. Ich meine das ist schon verwirrend genug fuer einen Anfaenger, und wir sollten nicht weitere Kanaele oeffnen. Wenn ein Wiki-Autor auf dem laufenden sein will, dann muss er den betroffenen Forumsbereich abonnieren, genauso wie der Maintainer.

ph1959de

Zitat von: Beta-User am 30 Januar 2018, 11:43:43
Zur Diskussion möchte ich aber noch den Gedanken geben, die Bedeutung der CommandRef an der Stelle nochmal zu unterstreichen. In die Richtung: "If you are looking for accurate and up-to-date documentation, this is the place to start with!".
Ich habe gerade mal die Vorlage "Infobox Modul" so geändert, dass sie immer den Hinweise
ZitatWichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!
enthält. Form und Inhalt können selbstverständlich leicht angepasst werden.

Kommentare sind natürlich auch willkommen.
Aktives Mitglied des FHEM e.V. | Moderator im Forenbereich "Wiki"

Beta-User

Zitat von: ph1959de am 30 Januar 2018, 12:36:31
Ich habe gerade mal die Vorlage "Infobox Modul" so geändert, dass sie immer den Hinweiseenthält. Form und Inhalt können selbstverständlich leicht angepasst werden.

Kommentare sind natürlich auch willkommen.
Finde ich grundsätzlich gut, aber "sofern vorhanden" ist m.E. irreführend: Das war doch gerade die einzig verpflichtende Vorgabe an Entwickler, dass es eine englische CommandRef geben _MUSS_ (was noch nichts über deren Qualität aussagt, da gab es wohl auch Fälle, in denen der Modulautor nur die englischen flags um einen deutschsprachigen Text gemacht hatte - aber davon eben mal abgesehen).

Vorschlag: "Bei allen FHEM-Modulen ist die aktuellste Dokumentation immer in der Commandref zu finden; im Zweifel maßgeblich ist die englische Fassung!"
Server: HP-elitedesk@Debian 12, aktuelles FHEM@ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

krikan

Zitat von: Beta-User am 30 Januar 2018, 11:16:55
Wenn das soweit in berufenen Augen ok ist, würde ich das dann noch auf der Hauptseite entsprechend verlinken (bzw. gerne auch jemand anderes...).
Du bist doch der Berufene.   :)
Also mach ruhig. Danke.

Zitatdie sehr übersichtliche und schlanke Seite sollte man m.E. auch nicht zu sehr aufbohren. Zur Diskussion möchte ich aber noch den Gedanken geben, die Bedeutung der CommandRef an der Stelle nochmal zu unterstreichen. In die Richtung: "If you are looking for accurate and up-to-date documentation, this is the place to start with!".
Kann ich gerne auf fhem.de aufnehmen. Auf der deutschen Fassung der Seite https://fhem.de/fhem_DE.html#Documentation hatte ich schon einmal mit einer stärkeren Betonung der commandref begonnen. Ausbauen möchte ich die Seite nicht. Vielmehr soll noch HOWTO aktualisiert und ins Wiki verlagert werden. Wer helfen mag, kann gerne loslegen. Siehe: https://forum.fhem.de/index.php/topic,72860.0.html

ZitatVorschlag: "Bei allen FHEM-Modulen ist die aktuellste Dokumentation immer in der Commandref zu finden; im Zweifel maßgeblich ist die englische Fassung!"
Ist  mir persönlich zu hart. Peters Variante gefällt mir besser, da es immer Ausnahmen gibt.

ph1959de

Zitat von: Beta-User am 30 Januar 2018, 13:01:34
... aber "sofern vorhanden" ist m.E. irreführend
Habe ich nur "auf die Schnelle" so formuliert, weil ich den Aufwand zur unterschiedlichen Behandlung von offiziellen / inoffiziellen (für die es ja keinen commandref-Eintrag gibt) Modulen gerade nicht spendieren kann.
Aktives Mitglied des FHEM e.V. | Moderator im Forenbereich "Wiki"

nils_

sollte man auch erwähnen das es einen unterschied gibt/geben kann zwischen lokaler und online commandref?
ich bin mir nicht sicher, ob dies auch jedem klar ist.
viele Wege in FHEM es gibt!

Beta-User

Link auf der Hauptseite ist eingebaut. Leider fällt das optisch nicht so sehr ins Auge, da grün auf grün, ich wollte den Text aber auch nicht zu sehr betonen. Wer Vorschläge hat, wie man das besser lösen kann: her damit...

Zitat von: ph1959de am 30 Januar 2018, 13:42:11
Habe ich nur "auf die Schnelle" so formuliert, weil ich den Aufwand zur unterschiedlichen Behandlung von offiziellen / inoffiziellen (für die es ja keinen commandref-Eintrag gibt) Modulen gerade nicht spendieren kann.
Schon irgendwie klar, und der Einwand, dass es bei inoffiziellen Modulen nicht paßt, ist ja auch richtig.
Wie wäre es mit "Bei offiziell mit FHEM ausgelieferten Modulen enthält im Zweifel immer die (englische) commandref die aktuellste Dokumentation."

Wenn es dann noch "Ausreißer" bei den "offiziellen" gibt, sollten wir die möglichst einfangen (deutscher Text in engl. commandref-flags bzw. unvollständig); das dürfte allg. im Sinne des Projekts sein ;) .
Server: HP-elitedesk@Debian 12, aktuelles FHEM@ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

Amenophis86

Naja eine Checkbox vor einem Update brauche ich auch nicht, darüber könnte man lediglich bei einem Major Relase oder wichtigen Änderungen wie umbennenung von Attributen nachdenken. Aber ein Hinweis zusätzlich bei der ersten Installtion sollte in meinen Augen nicht verkehrt sein. Und eine News-Device, welches einem Hinweise zu aktuellen Sachen gibt finde ich auch nicht schädlich. Aber ich wiederhole mich und bin still :)
Aktuell dabei unser neues Haus mit KNX am einrichten. Im nächsten Schritt dann KNX mit FHEM verbinden. Allein zwei Dinge sind dabei selten: Zeit und Geld...

Benni

Zitat von: Amenophis86 am 30 Januar 2018, 14:53:25
Und eine News-Device, welches einem Hinweise zu aktuellen Sachen gibt finde ich auch nicht schädlich. Aber ich wiederhole mich und bin still :)

Wie sollte denn das News-Device "gefüttert" werden?

Ein rssFeed-Device wäre evtl. eine Möglichkeit. Das gibt es schon und man bräuchte dafür nur einen geeigneten Feed, der von irgendjemandem mit den entsprechenden Nachrichten/Informationen befüllt werden müsste.

Für die Code-Changes ginge, nur mal so als Beispiel sowas jetzt schon:


define rssFHEMCodeChanges rssFeed https://svn.fhem.de/trac/log/trunk?format=rss&rev=HEAD&limit=200&mode=stop_on_copy 14400


Wie und wo man das sowas optisch sinnvoll einbinden könnte ist dann auch noch dieFrage.

Update: Teilweise präzisere Formulierung

Amenophis86

An RSS habe ich auch gedacht. Ich meinte aber auch nicht, dass jede Änderung in einem Modul eine Meldung generieren muss. Viel mehr in dieser Form:

- Es gibt ein "News" Device, welches regelmäßig auf Neuigkeiten prüft
- Neuigkeiten können sein:
-- Wichtige Änderungen in FHEM (Major Relase, Änderung von Attr. Namen (siehe aktuelle Diskussion))
-- SVN etc. Down oder Update (wie aktuell oben rechts im Forum)
- Entscheidung was News sind und nicht hat nur ein ausgewählter Kreis und nicht jeder Developer, sonst wird es zu voll und die Gefahr, dass es "missbraucht" wird steigt

Aber das ist eigentlich ein anderes Thema. Für das hier genannte Thema würde ich eher empfehlen, dass bei der Erstinstallation ein entsprechender Hinweis kommt. Aktuell erhält man ja die Sicherheitswarnung bezüglich allowed etc. Genau hier könnte man auch Informationen zur Doku verankern. Warum? Viele, die FHEM das erst Mal installiert haben noch keinen Plan wirklich und sehen diese Meldung als erste, so soll es ja auch sein. Wieso dann nicht direkt hier auf entsprechende Sachen wie CommandRef, Wiki, Forum etc. hinweisen mit dem Hinweis was die einzelnen Dinge sind? Ein Hinweis im Wiki auf der Startseite überlese ich, weil ich vielleicht direkt über die Google Suche in einem Beitrag gelandet bin, gleiches gilt fürs Forum. Wenn ich was neu installiere lese ich vermutlich doch recht genau, was das Programm mir bei der ersten Installation mitteilt.
Aktuell dabei unser neues Haus mit KNX am einrichten. Im nächsten Schritt dann KNX mit FHEM verbinden. Allein zwei Dinge sind dabei selten: Zeit und Geld...

pc1246

Moin
Ich will kurz mal auch etwas dazu posten. Ich finde es immer wieder laestig, dass, egal ob auf irgendwelchen (Blog-)Seiten oder auch im fhem-Wiki, das Aenderungsdatum ganz unten steht. So manches Mal habe ich waerend des Lesens schon vergessen, dass ich mal schauen wollte, wie alt der Eintrag ist. Warum macht man das nicht ganz prominent nach oben? Damit kann auch jede(r) Hilfesuchende recht gut erkennen wie aktuell der Eintrag ist, und als normal Denkende(r) ihre/seine Schluesse ziehen!
Nur so mein Gedanke
Gruss Christoph
HP T610
Onkyo_AVR;3 Enigma2; SB_Server ; SB_Player; HM-USB mit 15 HM-CC-RT-DN, 3 HM_WDS10_TH_O, 6 HM-Sec-SCo, 4 HM-Sec-MDIR-2, 1 HM-Sen-MDIR-O-2, 8 Ferion 5000 OW ; PhilipsTV; 4 harmony hub; Jeelink mit 9 PCA301; Somfy; S7-300; 3 LGW; HUE; HM-IP auf Charly

marvin78


Markus Bloch

Ich werde die kommenden Tage mal folgende Mediawiki Extension testen und ggf. im Wiki aktivieren: https://www.mediawiki.org/wiki/Extension:LastModified

Gruß
Markus
Developer für Module: YAMAHA_AVR, YAMAHA_BD, FB_CALLMONITOR, FB_CALLLIST, PRESENCE, Pushsafer, LGTV_IP12, version

aktives Mitglied des FHEM e.V. (Technik)

pc1246

Zitat von: Markus Bloch am 31 Januar 2018, 15:56:22
Ich werde die kommenden Tage mal folgende Mediawiki Extension testen und ggf. im Wiki aktivieren: https://www.mediawiki.org/wiki/Extension:LastModified

Gruß
Markus
Hallo Markus
Ich sehe jetzt nicht, dass das den gewuenschten Erfolg bringt! Das ist doch sogar schon implementiert, oder?
Nur eben leider ganz am Ende, und nicht ganz oben!?
Oder bin ich auf dem falschen Dampfer?
Gruss Christoph
HP T610
Onkyo_AVR;3 Enigma2; SB_Server ; SB_Player; HM-USB mit 15 HM-CC-RT-DN, 3 HM_WDS10_TH_O, 6 HM-Sec-SCo, 4 HM-Sec-MDIR-2, 1 HM-Sen-MDIR-O-2, 8 Ferion 5000 OW ; PhilipsTV; 4 harmony hub; Jeelink mit 9 PCA301; Somfy; S7-300; 3 LGW; HUE; HM-IP auf Charly

Markus Bloch

Die Extension würde das aber prominent oben neben dem Seitentitel postieren (siehe Screenshot auf der Seite). So das man sofort sieht, wann die letzte Aktualisierung erfolgte.

Gruß
Markus
Developer für Module: YAMAHA_AVR, YAMAHA_BD, FB_CALLMONITOR, FB_CALLLIST, PRESENCE, Pushsafer, LGTV_IP12, version

aktives Mitglied des FHEM e.V. (Technik)

pc1246

Ah
Sorry, das hatte ich nicht gesehen. Wenn man was anderes erwartet, sieht man den Wald vor lauter Baeumen nicht.
Finde ich gut, ist sogar fast noch besser, da sofort sichtbar ist wie alt der Eintrag ist.
Gruss Christoph
HP T610
Onkyo_AVR;3 Enigma2; SB_Server ; SB_Player; HM-USB mit 15 HM-CC-RT-DN, 3 HM_WDS10_TH_O, 6 HM-Sec-SCo, 4 HM-Sec-MDIR-2, 1 HM-Sen-MDIR-O-2, 8 Ferion 5000 OW ; PhilipsTV; 4 harmony hub; Jeelink mit 9 PCA301; Somfy; S7-300; 3 LGW; HUE; HM-IP auf Charly

krikan

Mir gefällt ein solch prominenter Hinweis auf die letzte Aktualisierung überhaupt nicht. Ich halte sie für deutlich kontraproduktiv.

Das letzte Aktualisierungsdatum sagt doch gar nichts über die Gültigkeit des Artikels oder gar die Qualität aus. Man muss die Infos aus Wikiartikeln im Zusammenhang mit den weiteren Infos, insbesondere der commandref, bewerten. Erst dann kann man etwas zur Gültigkeit/Qualität/Aktualität eines Artikels aussagen. Das erfordert die mMn für FHEM wichtige Lernbereitschaft.

Das prominente Platzieren der letzten Aktualisierung führt doch vmtl. nur dazu, dass Artikel mit altem Aktualisierungsdatum nicht gelesen werden, selbst wenn sie noch aktuell und gültig sind. Und das sind nicht wenige. Stattdessen fragt man direkt im Forum und erhöht den Supportaufwand. Natürlich kann ich auch unnötige Pseudoaktualisierungen vornehmen, um Aktualität zu dokumentieren.

Die commandref ist die Befehlsreferenz und das muss jedem klar sein. Deshalb wird/wurde das eben noch mehr betont. Ein Wiki bleibt aber ein Wiki. Es ergänzt und das sollte jedem klar sein. Es enthält eben auch Fehler. An der Beseitigung kann auch jeder mitwirken und man lernt auch daraus.

Gruß, Christian

Dr. Boris Neubert

Idee: im Template der Wikiseite einen Link auf Commandref vorsehen (bitte um Nachsicht, wenn das schon drin ist - kann das gerade nicht prüfen).
Globaler Moderator, Developer, aktives Mitglied des FHEM e.V. (Marketing, Verwaltung)
Bitte keine unaufgeforderten privaten Nachrichten!

krikan

Zitat von: Dr. Boris Neubert am 31 Januar 2018, 19:11:59
Idee: im Template der Wikiseite einen Link auf Commandref vorsehen (bitte um Nachsicht, wenn das schon drin ist - kann das gerade nicht prüfen).
In der klassischen Ansicht haben wir das vor ca. einem Jahr in die Sidebar aufgenommen.
In der mobilen Ansicht ist es leider nicht vorhanden; Sidebar ist dort nicht sichtbar.

pc1246

Hallo Christian
Es war ja nur eine Anmerkung von mir. Wenn ich ins Wiki gehe, um mir Hilfe zu suchen, dann wuerde ich, wenn ich sehe, dass der Artikel schon etwas aelter ist, einfach nur vorsichtiger daran gehen.
Beispiel Homematic RM-SD2. Da ist/war(?) hauptsaechlich der Aeltere beschrieben, trotzdem passte das meiste. Wenn jetzt die Trennung nicht so scharf ist, geht man als Unwissender zu sorglos heran, und es entsteht dieser Thread.
Haette man gleich gesehen, dass der Artikel aelter ist, waere man(ich) vorsichtiger an die Sache herangegangen, und haette die ebenfalls prominente Comandref, oder auch das Forum nochmals zu Rate gezogen. Aber eben auf eine positive Art, da man ja weiss, dass das Wiki evtl. nicht mehr 100% aktuell ist.
Mit Sicherheit gibt es genuegend User(innen), die sich so verhalten wuerden wie Du annimmst, und dann waere wieder der Tenor da, schau doch ins Wiki, wieso, nee das ist ja alt1
Es gibt also keine allgemeingueltige Loesung, und wir alle versuchen nur aus unseren Sichtweisen das Beste heraus zu holen.

Danke bei der Gelegenheit, fuer diese tolle Platform, sowohl fhem, als auch das Forum sowie das Wiki!

Gruss Christoph
HP T610
Onkyo_AVR;3 Enigma2; SB_Server ; SB_Player; HM-USB mit 15 HM-CC-RT-DN, 3 HM_WDS10_TH_O, 6 HM-Sec-SCo, 4 HM-Sec-MDIR-2, 1 HM-Sen-MDIR-O-2, 8 Ferion 5000 OW ; PhilipsTV; 4 harmony hub; Jeelink mit 9 PCA301; Somfy; S7-300; 3 LGW; HUE; HM-IP auf Charly

Prof. Dr. Peter Henning

Basierend auf der Einsicht, dass das Problem immer vor dem Bildschirm sitzt, schlage ich eine Änderung in den Standardmenüs von  FHEMWEB vor.

Bei frischen Installationen sollten dort nicht "Commandref" und "Remote doc" auftauchen, sondern ein fettes "Help".

Mit diesem Help-Button wird ein Frisch-Installierter auf eine Zwischenseite geleitet, auf der ihm die entsprechende Hierarchie dargestellt wird: ERST Commandref, dann Alles Weitere. Und da kann man auch noch weitere Hinweise anbringen, wie und wo zu suchen ist.

Erst wenn jemand manuell ein global attribute, sagen wir mal expertdocumentation=1 gesetzt hat, wird ihm die gegenwärtige Ansicht geboten.

LG

pah



rudolfkoenig

Ich bin offen fuer diese Aenderung.
Waere nett, wenn irgendwer den Inhalt dieser Zwischenseite vorbereitet.

JensS

Zitat von: Prof. Dr. Peter Henning am 03 Februar 2018, 16:20:48
Basierend auf der Einsicht, dass das Problem immer vor dem Bildschirm sitzt
Beim Majorupdate der 00_OWX.pm wurde die neue Moduldefinition erst Tage später in die commandref aufgenommen. Unerklärliche Abstürze waren die Folge. In dem Fall gab es die Info schneller im Forum. Sorry, aber nicht immer sitzt das Problem vor dem Userbildschirm.

Gruß Jens
Debian auf APU2C4, HM-CFG-USB2, SIGNALduino, HM-ES-PMSw1-Pl, TFA 30.3121, TFA 30.3125, ITS-150, PIR-5000, configurable Firmata USB & LAN, 1-wire: DS-18B20, DS-18S20, DS-2408, DS-2413, diverse I2C-Komponenten, zigbee2mqtt, ESPEasy etc.

Amenophis86

Zitat von: dirigent am 03 Februar 2018, 17:46:39
Sorry, aber nicht immer sitzt das Problem vor dem Userbildschirm.

Klar, nur, dass es ein Developer- und kein Userfehler war :) Werden es nie ganz verhindern können, aber verstehe was du meinst.
Aktuell dabei unser neues Haus mit KNX am einrichten. Im nächsten Schritt dann KNX mit FHEM verbinden. Allein zwei Dinge sind dabei selten: Zeit und Geld...

Prof. Dr. Peter Henning

Erstens gibt es keine "unerklärlichen Abstürze" - wir haben es immer noch mit einem kausalen System zu tun.

Und zweitens ist es ja wohl ein Unterschied, ob man mangels Test-Usern einen Fehler (und die kommen beileibe nicht nur in der Commandref vor ...) in einem weitgehend neuen Modul hat, oder mangels Lesewillens auf dem Schlauch steht.

Na, und drittens: Lies mal genauer, ich habe nicht "Userbildschirm" geschrieben

LG

pah

nils_

Zitat von: rudolfkoenig am 03 Februar 2018, 16:46:16
Waere nett, wenn irgendwer den Inhalt dieser Zwischenseite vorbereitet.

wäre das nicht die wiki-seite? -> https://wiki.fhem.de/wiki/Dokumentationsstruktur
oder zumindest ähnlich :)


man könnte ja auch noch die üblichen hilfetips dort aufführen:
- eventmonitor
- fhem startet nicht -> what to to?
- ...
viele Wege in FHEM es gibt!

Prof. Dr. Peter Henning

Ich habe diese Wiki-Seite gerade etwas aufgebohrt, eine Sektion "Don't Panic" soll noch hinzukommen.

LG

pah

SebMei

Die ComandRef ist doch die wichtigste Seite.
Die sollte deutlich ausgebaut werden mit umfangreicherer Beschreibung, möglichst vielen Beispielen und entsprechenden Links, damit man auch gleich sieht, was es sonst noch an Infos gibt und nicht erst noch lange suchen muss.
Aufgebohrte Wikiseiten und Zusatzseiten bringen nichts, nur weitere Verwirrung.

rudolfkoenig

ZitatDie sollte deutlich ausgebaut werden mit umfangreicherer Beschreibung, möglichst vielen Beispielen
Ich sehe das anders. Commandref sollte in guter alter UNIX man-page Manier vollstaendig aber kurz sein. Es sollte nicht die Pflicht des Modulautors sein, jeden Anwendungsfall mit einem vollstaendigen Rezept fuer den unerfahrenen Benutzer zu beschreiben. Leute, die man-Pages gewohnt sind, werden von detaillierter Dokumentation genervt, ein Anfaengerdoku-Pflicht wuerde sie nur abschrecken.

Benutzer, die gerade ein Problem geloest haben, koennen das fuer Andere besser beschreiben, und fuer sowas ist der FHEM-Wiki da. Nebenbei verteilt dieses Verfahren die Last der Dokumentation auf mehrere Schulter.

Ueber fremde Seiten haben wir keine Kontrolle, wer da Hilfe findet, sollte sich bei Problemen auch da beschweren.

SebMei

Für Modulautoren, die sich Tag und Nacht damit befassen, mag das ja ausreichend sein.

Aber Fhem ist doch für Anwender und sollte doch anwenderfreundlich gestaltet sein. Und die Mehrzahl der Fhem-user sind nun mal keine Modulautoren oder man-Pages gewohnt.
In der Dokumentation heißt es doch: ,,commandref_DE.html enthält eine detaillierte Beschreibung aller Module und Features" ; detailliert und nicht kurz!
Es ist sicher nicht nötig/möglich jeden Anwendungsfall zu beschreiben, aber Beispiele haben schon immer sehr zum Verständnis beigetragen.
Die vielen Fragen im Forum sind doch ein Zeichen für Bedarf an Verbesserung.

Dr. Boris Neubert

Zitat von: SebMei am 11 Juni 2018, 19:44:12
Es ist sicher nicht nötig/möglich jeden Anwendungsfall zu beschreiben, aber Beispiele haben schon immer sehr zum Verständnis beigetragen.
Die vielen Fragen im Forum sind doch ein Zeichen für Bedarf an Verbesserung.

Die Regel ist, dass die Commandref alle Parameter, Kommandos und Attribute eines Geräts auflistet und beschreibt, so dass man versteht, was diese tun, und diese Funktionen des Moduls nutzen kann. Einfache Beispiele sind dabei hilfreich und häufig auch vorhanden.

Komplexe Anwendungsfälle sprengen den Rahmen und gehören ins Wiki. Uns ist bewusst, dass durch die Entkoppelung von Commandref und Wiki das Wiki manchmal veraltet ist. Für Module in häufigem Gebrauch finden sich aber meist Enthusiasten, die das Wiki auf den neuesten Stand bringen. Letzlich lebt FHEM aber von der Freiwilligkeit und dem guten Willen der Entwickler. Und diese wird niemand zwingen können, ausführliche Commandrefs zu beschreiben, wenn sie das nicht wollen.

Als Entwickler fände ich es schön, wenn allen, denen in Forum geholfen wird, die Ergebnisse der Hilfe dokumentieren und zum Wiki beitragen. Diesen Anspruch erfüllen die meisten Anwender aber ebensowenig, wie ich als Entwickler den Anspruch einiger Anwender erfülle, in der Commandref wesentlich ausführlicher zu werden, als ich das schon bin.

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

Beta-User

Zitat von: SebMei am 11 Juni 2018, 19:44:12
,,commandref_DE.html enthält eine detaillierte Beschreibung aller Module und Features"
Punkt für dich, steht tatsächlich (mind.) an zwei Stellen auf https://fhem.de/fhem_DE.html.
Vielleicht sollte man das der Realität anpassen?
Ansonsten: +1 für manpage-like
Das reicht auch nach meiner Erfahrung als Anwender in der Regel, um das jeweilige Modul in Betrieb zu nehmen oder schnell was nachzuschlagen - und nein, ich habe FHEM eingerichtet, ohne Perl-Kenntnisse zu haben (oder eine andere Programmiersprache wirklich zu beherrschen, war aber manpages gewohnt). (Ich empfinde es im Gegenteil als lästig, wenn zu viel drin steht, das lenkt nur ab...). Für den Rest gibt es andere Quellen, und gelesen haben sollte man eigentlich doch nur das Einsteiger-pdf und die jeweilige commandref. Wenn das im Post zum Ausdruck kommt und die Sufu nicht im Forum und Wiki mit den Schlüsselbegriffen des Fragers eine klare Antwort ergibt, bekommt man doch hier in der Regel eine nette Antwort oder einen Link, der einem weiterhilft. Was will man mehr?

Die vielen Fragen rühren oft daher, dass die Betreffenden
- Transferleistungen nicht erbringen können oder wollen
- die SuFu nicht nutzen (Fehler in einem Modul führen in der Regel zu mind. 5 neuen Threads zu genau dem Thema...)
- irgendeine veraltete Anleitung aus den Untiefen des Web ziehen und dann hier Hilfe erwarten
- sich nicht trauen, auch mal was auszuprobieren

Dass man detailliert in der (deutschen) Commandref schreiben kann, was man will einschließlich unzähliger Beispiele, und trotzdem immer wieder dieselben Punkte nicht verstehen, sieht man sehr gut an der überbordenden Doku zu DOIF...

Zu at, notify, watchdog und perl ist alles viel kürzer, dafür steht aber eigentlich alles drin, was man braucht, um Dinge zu lösen. Man muß nur das Problem erst mal verstanden haben und beschreiben können.

Alles kein Grund, Entwickler von Wichtigerem abzuhalten.

Just my2ct
Beta-User
Server: HP-elitedesk@Debian 12, aktuelles FHEM@ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

Benni

Zitat von: SebMei am 11 Juni 2018, 19:44:12
Für Modulautoren, die sich Tag und Nacht damit befassen

Nein! Genau das tun sie eben nicht!

Die Meisten haben einen Beruf, eine Familie und auch noch andere Freizeitaktivitäten.

Die Modulautoren haben sich quasi "verpflichtet" ihre Module in der Commandref zu dokumentieren (bindend ist dabei übrigens nur die englische Commandref). Weiterhin haben sie sich dazu "verpflichtet" Ihre Module u.a. hier im Forum zu supporten. Dokumentation und detailliert bedeutet übrigens nicht automatisch, jeden möglichen Anwendungsfall mit Beispielen in zig Varianten zu beschreiben.

Wem das nicht genügt, der darf gerne selbst Hand anzulegen und sich bspw. im Wiki beteiligen. Das steht jedem (!) offen und das ist auch der richtige Ort um verschiedenste Anwendungsfälle zu beschreiben. Schön natürlich, wenn sich dort der jeweilige Modulautor selbst die Mühe macht und einbringt, aber verlangen kann/darf man das von ihm nicht.

Was hier immer wieder gerne vergessen wird ist, dass FHEM ein Community-Projekt ist, an dem sich jeder nach seinen Möglichkeiten beteiligen darf (Community=Gemeinschaft!)

Das waren meine 2 Ct. dazu!
gb#

nils_

Zitat von: Dr. Boris Neubert am 11 Juni 2018, 20:22:21
Die Regel ist, dass die Commandref alle Parameter, Kommandos und Attribute eines Geräts auflistet und beschreibt, so dass man versteht, was diese tun, und diese Funktionen des Moduls nutzen kann. Einfache Beispiele sind dabei hilfreich und häufig auch vorhanden.
das verstehe ich unter detailiert, deswegen finde ich (!) es nicht falsch wenn irgendwo steht
Zitat,,commandref_DE.html enthält eine detaillierte Beschreibung aller Module und Features"
für mehr -> wiki !


Zitat von: Benni am 11 Juni 2018, 20:58:17
Die Meisten haben einen Beruf, eine Familie und auch noch andere Freizeitaktivitäten.
waaaaaaaaaaaas? nicht nur fhem??? skandal....
also beruf kündigen, familie ist auf ein minimum zu reduzieren und Freizeitaktivitäten sind sofort einzustellen!! 


;D ;D ;D

Zitat von: Benni am 11 Juni 2018, 20:58:17
Die Modulautoren haben sich quasi "verpflichtet" ihre Module in der Commandref zu dokumentieren (bindend ist dabei übrigens nur die englische Commandref).
da passt DOIF als Beispiel aber dann nicht so gut. denn die englische beschreibt nicht alles (?). die deutschte ist da eher erschlagend/umfangreich, beschreibt aber alles mit mindestens einem Beispiel!


Zitat von: Benni am 11 Juni 2018, 20:58:17
Wem das nicht genügt, der darf gerne selbst Hand anzulegen und sich bspw. im Wiki beteiligen. Das steht jedem (!) offen und das ist auch der richtige Ort um verschiedenste Anwendungsfälle zu beschreiben. Schön natürlich, wenn sich dort der jeweilige Modulautor selbst die Mühe macht und einbringt, aber verlangen kann/darf man das von ihm nicht.

Was hier immer wieder gerne vergessen wird ist, dass FHEM ein Community-Projekt ist, an dem sich jeder nach seinen Möglichkeiten beteiligen darf (Community=Gemeinschaft!)

Das waren meine 2 Ct. dazu!
full ack :)


viele Wege in FHEM es gibt!

marvin78

DOIF ist in der englischen Commandref ausreichend dokumentiert (aus verschiedenen Gründen aus meiner Sicht sogar besser, als im deutschen Teil). Der ganze zusätzliche Kram im deutschen Teil gehört aus meiner Sicht in das Wiki ;)

nils_

Zitat von: marvin78 am 12 Juni 2018, 08:14:06
DOIF ist in der englischen Commandref ausreichend dokumentiert (aus verschiedenen Gründen aus meiner Sicht sogar besser, als im deutschen Teil). Der ganze zusätzliche Kram im deutschen Teil gehört aus meiner Sicht in das Wiki ;)
es wird beschrieben was DOIF tut bzw. wofür man es einsetzen kann.
das finde ich auch ok!

aber es passt dann definitiv nicht dazu:
Zitat von: Dr. Boris Neubert am 11 Juni 2018, 20:22:21
Die Regel ist, dass die Commandref alle Parameter, Kommandos und Attribute eines Geräts auflistet und beschreibt, so dass man versteht, was diese tun, und diese Funktionen des Moduls nutzen kann. Einfache Beispiele sind dabei hilfreich und häufig auch vorhanden.
jedenfalls der englische Teil.....


und bitte nicht falsch verstehen, ich will nicht auf dem DOIF Teil rumhacken. der deutsche ist anteil ist ja umfassend !
den schlage ich bei Fragen und Suche nach Fehlern eh nach :) und weil ich da öfter mal reingucke, ist mir der unterschied zwischen "de" und "en" Teil bekannt.
wie es bei weiteren modulen aussieht weiß ich nicht, und ich will auch jetzt nicht alle angucken.
in meiner erinnerung müsste es aber auch module geben, die im englischen und deutschen Teil identische Texte, nämlich die englischen, in der commandref stehen haben.
viele Wege in FHEM es gibt!

marvin78

Es gibt noch mehr Module, die sich nicht an die Vorgaben halten. Man sollte aber nicht auf den Entwicklern rumhacken. Zu DOIF gibt es zum Beispiel einen fantastischen Support hier im Forum, was in der Form auch nicht selbstverständlich ist. Das Forum ist ohnehin das wichtigste Supportmedium nach der commandref. Auch wenn es oft falsch genutzt wird (die Suche wird ignoriert) hilft es doch sicher den meisten Usern bei ihren Problemchen. Oft wird ja nur ein Denkanstoß benötigt. Für die, die tatsächlich denken können, reicht das in der Regel und dafür ist das Forum perfekt.

Das Wiki ist aus meiner Sicht nice to have nicht, mandatory. Auch Beispiele generell sind nicht mandatory, wenn die commandref alle Parameter beschreibt.

HubertM

Mit euren Posts bestätigt ihr doch nur, dass Fhem nur etwas für erfahrene Benutzer ist. Und selbst die sind sich nicht einig. Einsteiger müssen sich mühsam alles zusammensuchen. Im Forum werden Fragesteller oft niedergemacht mit ,,lies doch gefälligst die (kurze) commandref".

Was nützt ein tolles Modul, wenn die Entwickler es aus Zeitmangel oder Wichtigerem nicht ordentlich beschreiben können.

Vielleicht sollte man den Namen ,,Fhem" der Realität anpassen in "Ehem"
(Einsteigerunfreundliche Hausautomatisierung und Energie-Messung)

marvin78

Du liegst falsch. Einsteigern wird hier das Leben sehr leicht gemacht. Aber faule Menschen oder Menschen, die keine Lust haben, etwas Arbeit reinzustecken, würde ich empfehlen, zu einem Klicki-Bunti System zu wechseln, das genau für diese Zielgruppe konzipiert wurde. Jedes System hat seine Zielgruppe. FHEM ist etwas für den ambitionierten User aber nicht nur für erfahrene. Das zeigen unzählige Beispiele.

Aber aus der Diskussion halte ich mich nun raus. Das ist gefühlt das 100ste mal.

vbs

Man kann über FHEM viel Positives sagen - aber dass es besonders einsteigerfreundlich sei, ist natürlich Quatsch... so ehrlich muss man dann doch mal sein. Ist aber eben einfach eine Frage der gewünschten Zielgruppe.

marvin78

Was ihr falsch macht ist die Gleichsetzung von Erfahrung und Ambitioniertheit. Erfahrung in FHEM hat zu Beginn niemand, kann aber sehr wohl durch Ambition und Fleiß diese Erfahrung erlangen. Einsteiger sind nicht gleichzeitig auch wenig ambitioniert. Aber das ist die Zielgruppe: Ambitionierte User. Das schließt Einsteiger nicht aus denn sonst würde niemals jemand erfahren werden. Einsteigern wird das Leben hier im Forum und eine sehr detaillierte Doku unterstützt durch Forum und Wiki sehr wohl sehr leicht gemacht, WENN sie ambitioniert sind.

Bevor ich mir selbst Programmieren mit php, Perl und JS beigebracht habe, habe ich auch keinerlei Erfahrung in diesen Bereichen gehabt. Und trotzdem fiel es mir extrem leicht, das zu erlernen, weil ich genau das machen wollte: lernen.

Prof. Dr. Peter Henning

Meine erste Open Source-Software habe ich 1987 auf den Fish-Disks für den Commodore Amiga veröffentlicht. Wenn ich mich richtig erinnere, war das ein Postscript-Druckertreiber. Damals entstand die Idee von Open Source Software als "as-is commodity": Man nimmt sie, nutzt sie, und meckert nicht darüber. Wenn man Ideen zur Verbesserung hat, wendet man sich respektvoll an denjenigen, der das Ding geschrieben hat - oder schreibt seinen eigenen Kram. Und wenn einem die Dokumentation nicht ausreicht, hat man Pech gehabt.

Die Zeiten sind aber andere, und auch FHEM ist anders.

FHEM ist erstens anders, weil es nicht von einer Einzelperson entwickelt wird. Die etwa 100 Enthusiasten, die es aktiv ausbauen, sind schon ein sehr heterogener Haufen. Nicht einmal über solche Dinge wie die Vereinsmitgliedschaft haben wir uns einigen können. Insofern ist unser Paradigma das des Basars, nicht das der Kathedrale (siehe https://de.wikipedia.org/wiki/Die_Kathedrale_und_der_Basar).Viele Probleme mit mauligen oder gar frechen Newcomern im Forum rühren daher, dass diese das Prinzip des Basars eben nicht verstanden haben.

==> Den Wikipedia-Artikel über die Kathedrale und den Basar habe ich gerade auf der Wiki-Seite zum Thema Dokumentationsstruktur verlinkt. Vielleicht sollte man ihn auch oben bei den Anfängerfragen anpinnen - und klar auf die 19 Grundsätze von Raymond verweisen.

FHEM ist aber zweitens anders, weil es keine Spezialsoftware für einen eng begrenzten Anwendungsfall ist - sondern eine nahezu universelle Automatisierungsplattform darstellt. Das lockt viele Anwender, die weder Ahnung von Automatisierung haben, noch diese erwerben wollen. Sondern einfach einen nützlichen Idioten (aka "Programmierer" aka "Techie") suchen, der ihnen das realisiert. Leider treffen wir diesen Anwendertyp oft im Bereich der höheren Einkommen (und damit der höheren Ansprüche an ein SmartHome) an. Und damit sind wir ein bisschen bei den "anderen Zeiten" - wiewohl, möchte man mit Faust ausrufen
ZitatWas Ihr den Geist der Zeiten heißt, das ist im Grund der Herren eigner Geist, in dem die Zeiten sich bespiegeln
Denn es scheint tatsächlich zum Zeitgeist zu gehören, dass man beschimpft wird, wenn a.) kostenlose Software und b.)kostenfreie Beratung nicht das erfüllen, was der Nachfrager haben will.

Ich glaube, dass wir hier mal einen Riegel vorschieben sollten. Und klar und deutlich jedem Neuanmelder (und so manchem Altgedienten) sagen sollten:

Man bekommt nur etwas heraus, wenn man selbst Zeit investiert und anderen etwas gibt.

LG

pah

Rudi352

Der nächste ellenlange Beitrag völlig am Thema vorbei.

Es geht doch darum Fhem übersichtlich und anwenderfreundlich zu gestalten.
Da sich die Helden gegenseitig heftig zustimmen, zeigt doch, dass daran keine Interesse besteht.

Gerade als Professor sollte (!!) man doch die Fähigkeit besitzen Wissen zu vermitteln anstatt in übergroßen Lettern Sprüche zu klopfen.

Dr. Boris Neubert

Hallo,

ich stimme pahs Beitrag inhaltlich vollständig zu.

Zitat von: HubertM am 12 Juni 2018, 09:54:57
Vielleicht sollte man den Namen ,,Fhem" der Realität anpassen in "Ehem"
(Einsteigerunfreundliche Hausautomatisierung und Energie-Messung)

@HubertM:  Es ist völlig in Ordnung, wenn Du eine andere Meinung hast als die Mehrheit der Kontributoren zu FHEM, die sich hier geäußert haben. Ich bitte Dich aber zu überprüfen, mit welchem Respekt Du den Mitarbeitern an FHEM (Entwickler, Helfer im Forum, Autoren im Wiki, ...) entgegentreten möchtest. Für mich ist Dein Beitrag inakzeptabel.

Viele Grüße
Boris

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

Dr. Boris Neubert

Hallo,

Zitat von: Rudi352 am 12 Juni 2018, 16:56:58
Da sich die Helden gegenseitig heftig zustimmen, zeigt doch, dass daran keine Interesse besteht.

Gerade als Professor sollte (!!) man doch die Fähigkeit besitzen Wissen zu vermitteln anstatt in übergroßen Lettern Sprüche zu klopfen.

Auch Dich bitte ich zu überprüfen, mit welchem Respekt Du den Mitarbeitern an FHEM (Entwickler, Helfer im Forum, Autoren im Wiki, ...) entgegentreten möchtest.

Zitat von: Rudi352 am 12 Juni 2018, 16:56:58
Es geht doch darum Fhem übersichtlich und anwenderfreundlich zu gestalten.

Es geht Dir darum, Fhem übersichtlich und anwenderfreundlich zu gestalten. Mir nicht. Ich halte es mit Marvin78: es geht mir u.a. darum, zu einem Hausautomationssystem beizutragen, dass dem ambitionierten Anwender reichhaltige Möglichkeiten bietet. Und das ist meine persönliche Sicht - andere Kontributoren haben andere Motive.

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

Prof. Dr. Peter Henning

Zitatdass daran keine Interesse besteht
;D ;D

Wir haben hier zwei Mitdiskutanten, die zwar selbst nur wenig bis gar keine konstruktiven Beiträge zu FHEM leisten - aber erstens gerne die Posts von anderen kritisieren, zweitens genaue Vorstellungen über die Ziele von FHEM haben und drittens auch noch genau wissen, was andere Menschen tun und lassen sollten.

Daher kann ich dem Obigen nur zustimmen: Daran besteht hier kein(e) Interesse. Wie wäre es also damit, sich eine andere Spielwiese zu suchen ?

LG

pah


andies

Zitat von: marvin78 am 12 Juni 2018, 09:58:02
Aber aus der Diskussion halte ich mich nun raus. Das ist gefühlt das 100ste mal.
Stimmt, wir diskutieren das oft und vermutlich immer wieder. Ich habe ja am Anfang auch gemeckert, weil ich fast wahnsinnig geworden bin (ich habe nix kapiert: ,,Internals", ,,Readings" etc). Hinzu kam, dass ich eher der Wiki-Typ bin, die Commandref ist manchmal schon rein sprachlich ein Problem (= fast unlesbar).

Das wird nur was, wenn man dran und vor allem freundlich bleibt, das kann man den beiden da oben schon mal ins Stammbuch schreiben. Und selber aktiv wird. Ich habe halt angefangen im Wiki reinzuschreiben, bis ich es kapiert habe. Danach lief es auf einmal.

Das Ding ist halt kostenlos, Leute. Jedenfalls in Euro. Und weil es wertvoll ist, muss irgendwo der Haken sein. Der ist: man muss nicht Geld, sondern Arbeit reinstecken!


Gesendet von iPhone mit Tapatalk Pro
FHEM 6.1 auf RaspPi3 (Raspbian:  6.1.21-v8+; Perl: v5.32.1)
SIGNALduino (433 MHz) und HM-UART (868 MHz), Sonoff, Blitzwolf, Somfy RTS, CAME-Gartentor, Volkszähler, Keyence-Sensor, Homematic-Sensoren und -thermostat, Ferraris-Zähler für Wasseruhr, Openlink-Nachbau Viessmann

Prof. Dr. Peter Henning

Das genau ist der Punkt: FHEM ist kostenlos, aber nicht umsonst.
Der Preis ist persönliches Engagement - und das Ergebnis persönliche Zufriedenheit.

LG

pah

SebMei

Leute,
merkt ihr eigentlich nicht, dass ihr euch um Kopf und Kragen redet um eure Existenz zu rechtfertigen?
Anwenderfreundlich, nein Danke. Das ist euer Motto.
,,Ehem" ist da ganz richtig!

Frohes Zustimmunggeben.

Dr. Boris Neubert

Zitat von: SebMei am 12 Juni 2018, 20:10:02
Leute,
merkt ihr eigentlich nicht, dass ihr euch um Kopf und Kragen redet um eure Existenz zu rechtfertigen?
Anwenderfreundlich, nein Danke. Das ist euer Motto.
,,Ehem" ist da ganz richtig!

Frohes Zustimmunggeben.

Dein Beitrag ist völlig unangemessen.

Da in diesem Thema nun auch nichts mehr konstruktives zu erwarten ist, schließe ich das Thema nun.
Globaler Moderator, Developer, aktives Mitglied des FHEM e.V. (Marketing, Verwaltung)
Bitte keine unaufgeforderten privaten Nachrichten!