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!