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

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!