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

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.