Autor Thema: Umgang mit Widersprüchen zwischen CommandRef, Wiki und dem Rest des Internets  (Gelesen 5652 mal)

Offline nils_

  • Developer
  • Sr. Member
  • ****
  • Beiträge: 924
viele Wege in FHEM es gibt!

Offline Dr. Boris Neubert

  • Global Moderator
  • Hero Member
  • ****
  • Beiträge: 4220
Globaler Moderator, Developer, aktives Mitglied des FHEM e.V. (Marketing, Verwaltung)
Bitte keine unaufgeforderten privaten Nachrichten!

Online Beta-User

  • Hero Member
  • *****
  • Beiträge: 3816
Antw:Umgang mit Widersprüchen zwischen CommandRef, Wiki und dem Rest ..
« Antwort #17 am: 30 Januar 2018, 10:32:01 »
Wenn ich nochmal zurückkommen darf auf
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
Zitat
Das 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-T5740 mit Debian stretch (i386) + aktuellem FHEM | ConfigDB | VCCU mit einiger HM-Hardware | MySensors seriell (2.3.1-beta@RS485, div. konkrete Hardware, u.a. einige DS18B20) | Milight@ESP-GW | SIGNALduino | MapleCUN

Offline Dr. Boris Neubert

  • Global Moderator
  • Hero Member
  • ****
  • Beiträge: 4220
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!

Offline krikan

  • Global Moderator
  • Hero Member
  • ****
  • Beiträge: 5984
Antw:Umgang mit Widersprüchen zwischen CommandRef, Wiki und dem Rest
« Antwort #19 am: 30 Januar 2018, 10:45:15 »
Hallo Beta-User!

Zitat
Konkret hätte ich folgenden Vorschlag

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

Gruß, Christian

Offline nils_

  • Developer
  • Sr. Member
  • ****
  • Beiträge: 924
@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 :)
... 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
« Letzte Änderung: 30 Januar 2018, 11:18:59 von nils_ »
viele Wege in FHEM es gibt!

Online Beta-User

  • Hero Member
  • *****
  • Beiträge: 3816
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-T5740 mit Debian stretch (i386) + aktuellem FHEM | ConfigDB | VCCU mit einiger HM-Hardware | MySensors seriell (2.3.1-beta@RS485, div. konkrete Hardware, u.a. einige DS18B20) | Milight@ESP-GW | SIGNALduino | MapleCUN

Offline Amenophis86

  • Hero Member
  • *****
  • Beiträge: 2448
  • Anti-Statement befreite Zone ;)
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.
FHEM auf Raspberry3, Betriebssystem Jessy, HMLan, HM Komponenten, LD382A, H801, Sonoff, Harmony Hub und vieles mehr. Einfach ein tolles universelles System

Offline Benni

  • Developer
  • Hero Member
  • ****
  • Beiträge: 1821
  • FHEMinist

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.
FHEM (FL 9.9) (configDB+DbLog) auf Debian Wheezy.
Jede Menge HM mit 2x HMUART (WeMos+esp-link) über VCCU.
UniRoll an CUL868. Sebury F2-2 RFID über ESPEasy
Module: 98_rssFeed und 98_QRCode

Offline Dr. Boris Neubert

  • Global Moderator
  • Hero Member
  • ****
  • Beiträge: 4220
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!

Online Beta-User

  • Hero Member
  • *****
  • Beiträge: 3816
Apropos: Wenn du fhem.de schon in der Auflistung mit drin hast, gehört das m.E. an die erste Stelle.
Agreed und erledigt.

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-T5740 mit Debian stretch (i386) + aktuellem FHEM | ConfigDB | VCCU mit einiger HM-Hardware | MySensors seriell (2.3.1-beta@RS485, div. konkrete Hardware, u.a. einige DS18B20) | Milight@ESP-GW | SIGNALduino | MapleCUN
Zustimmung Zustimmung x 2 Liste anzeigen

Offline rudolfkoenig

  • Administrator
  • Hero Member
  • *****
  • Beiträge: 19006
Zitat
Irgendwann 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.
Zustimmung Zustimmung x 3 Liste anzeigen

Offline ph1959de

  • Moderator
  • Sr. Member
  • ***
  • Beiträge: 878
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
Zitat
Wichtig: 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.
[Fhem auf BeagleBone Black (Debian) | FS20, FHT (CUL) | HomeMatic (HMLAN+HMUART) | PCA301 (JeeLink)...]
Gefällt mir Gefällt mir x 1 Liste anzeigen

Online Beta-User

  • Hero Member
  • *****
  • Beiträge: 3816
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-T5740 mit Debian stretch (i386) + aktuellem FHEM | ConfigDB | VCCU mit einiger HM-Hardware | MySensors seriell (2.3.1-beta@RS485, div. konkrete Hardware, u.a. einige DS18B20) | Milight@ESP-GW | SIGNALduino | MapleCUN

Offline krikan

  • Global Moderator
  • Hero Member
  • ****
  • Beiträge: 5984
Antw:Umgang mit Widersprüchen zwischen CommandRef, Wiki und dem Rest
« Antwort #29 am: 30 Januar 2018, 13:22:22 »
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.

Zitat
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!".
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

Zitat
Vorschlag: "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.

 

decade-submarginal