Dokumentation / WIKI - Diskussion

thobastian

Hallo alle Zusammen,

wie ich hier schon schrieb, komme ich vom Tool Openhab , was mir einfach zu kompliziert war. Openhab kann zwar erstmal mehr, aber muss komplizierter konfiguriert werden. So sehe ich das zumindest.

Hier bei euch fühle ich mich wohl und war auch überrascht, wieviel Doku ihr dem Anfänger anbietet.

Aber warum habt ihr kein Wiki? Ich habe erst Homekit ausprobiert und festgestellt, dass YAKA viel besser ist. Außerdem baut ihr sehr schnell eine Doku im Forum auf. Im Forum ist eine Dokumentation aber immer schwer zu finden. Neue User werden abgeschreckt. Und es ist schade, wenn sogar Videos zur Konfiguration von Adaptern angeboten werden und keiner findet sie….oder?

Also, was haltet ihr von Wiki? oder andere Möglichkeiten?

Ciao, Thomas

Homoran

Hallo Thomas,

Im Moment ist alles im Umbruch. Wir arbeiten an einer neuen Website.

Die Idee mit dem Wiki taucht hier im Forum immer wieder auf. Es gibt Gründe dafür und dagegen.

Dagegen spricht dass es noch eine Quelle geben wird, die gepflegt werden müsste.

Im Moment gibt es

Github (hier machen Entwickler das readme)
Trello als Übersicht von bugs und der geplante Entwicklung
die Website als Nachschlagewerk
das Forum für Fragen
- bei vielen gleichen Fragen ein Hinweis, dass in der Doku was fehlt (oder keiner liest :P )

Gruß

Rainer

thobastian

Das Wiki könnte sich nahtlos in die derzeitige Menüstruktur der Webseite einfügen. Da sehe ich kein Problem.

Die Adapter sind aus meiner Sicht viel zu schlecht dokumentiert. Das soll aber keine negative Wertung sein. Es gibt auch Ausnahmen.

Die Webseite zeigt Informationen an unterschiedlichen Stellen: Scripte, Adapter, Schnittstellen, usw…

Das könnte zusammen gefasst werden.

Github ist für mich persönlich ein rotes Tuch und zu Entwicklerlastig. Ein Wiki wird auch durch Nutzer gefüllt.

und wie gesagt, das Forum ist das schlechteste aller Dokumentationen. Foren sind für Fragen und Aufzeigen von Info-Lücken klasse, aber sonst...

Homoran

~~@thobastian:~~

Die Adapter sind aus meiner Sicht viel zu schlecht dokumentiert. `
Das stimmt.

~~@thobastian:~~

Es gibt auch Ausnahmen. `
Der weitere Ausbau der Website wurde vorübergehend auf Eis gelegt, da http://forum.iobroker.net/viewtopic.php?f=23&t=5894&p=60532#p60515 auf ganz andere Basis aufbaut und die ersten Dateien bereits konvertiert wurden.

~~@thobastian:~~

und wie gesagt, das Forum ist das schlechteste aller Dokumentationen. `
Das Forum ist dafür auch nicht gedacht, sondern nur zur Diskussion von Verständnisproblemen. Erster Anlaufpunkt soll immer die Website sein.

~~@thobastian:~~

Das könnte zusammen gefasst werden. `
Da gibt es definitiv einige andere Meinungen ;-)

Einsteiger wollen sich z.B. nicht mit Skripten beschäftigen, um nur eine zu nennen.

~~@thobastian:~~

Ein Wiki wird auch durch Nutzer gefüllt. `
s.o. jeder Nutzer hat andere Sichtweisen. Ein Scripter kann es oft nicht nachvollziehen, was ein Noob alles nicht versteht.

Solche Einträge müssten dann wieder noob-gerecht geändert werden.

Zum Thema Wiki gibt es bereits einige Diskussionen. Musst einfach mal suchen. Das muss hier nicht nochmal zum x-ten mal in einem separaten Thread aufgekocht werden.

Gruß

Rainer

thobastian

Hallo Rainer,

ich möchte euch nicht auf den Wecker gehen, aber macht es nicht Sinn, grundsätzlich aus den Foren gesammelte Erkenntnisse, auf einer Webseite zu veröffentlichen?

Gibt es da nicht ein Gremium bei euch, in dem sowas diskutiert wird?

Dein Verweis auf eine Forensdiskussion ist nicht hilfreich. Ich habe im Forum gesucht und irgendwann aufgegeben. Es gab etliche Suchbegriffe mit"Wiki"…

Naja, aber ihr müßt es wissen.

Ciao, Thomas

Homoran

~~@thobastian:~~

ich möchte euch nicht auf den Wecker gehen, aber macht es nicht Sinn, grundsätzlich aus den Foren gesammelte Erkenntnisse, auf einer Webseite zu veröffentlichen? `
So schnell geht mir keiner auf den Wecker.

~~@thobastian:~~

Gibt es da nicht ein Gremium bei euch `
Lange war ich das Germium, da habe ich es ganz allein gemacht, Bluefox hat einges neben der Programmierung gemacht, davon wollte ich ihn eigentlich entlasten. Jetzt denke ich, dass wir einen Weg gefunden haben, dass da auch mehrere etwas reißen könnten, wenn sie es denn täten….

~~@thobastian:~~

Dein Verweis auf eine Forensdiskussion ist nicht hilfreich. Ich habe im Forum gesucht und irgendwann aufgegeben. Es gab etliche Suchbegriffe mit"Wiki"… `
Sorry, das war nicht meine Absicht, bin nur im Moment im Büro und hatte nicht die Zeit die Threads zu suchen, hole ich gerne nach.

~~@thobastian:~~

Naja, aber ihr müßt es wissen. `
Das klingt gar nicht gut, feedback ist immer hilfreich.

Gruiß

Rainer

PS wie stellst du dir vor "alles aus dem Forum" auf der Website zu veröffentlichen? Die Frage ist so gemeint wie sie da steht. Mich interessiert das wie!

Jeeper.at

Also meines Erachtens ist es viel zielführender die User hier zu bewegen einen sprechenden Threadtitel zu vergeben. Ist das Problem gelöst dann im Titel mit [gelöst] kennzeichnen.

Weiteres für jedes Problem einen neuen Thread aufzumachen. Dann wird nichts verwässert. Gelöste Threads sollten zeitnah geschlossen werden.

Das halte ich viel besser und praktikabler als ein WIKI (Davon habe ich schon zu viele sterben gesehen).

Das Forum und nur das Forum ist die Quelle aller Infos (Ausnahme die Adapter Dokus, die gehören auf die Webseite)

Lg

Günther

Homoran

~~@Homoran:~~

hatte nicht die Zeit die Threads zu suchen, hole ich gerne nach. `

Wie versprochen:

http://forum.iobroker.net/viewtopic.php?f=8&t=5214

eine reaktion:

http://forum.iobroker.net/viewtopic.php … 545#p34545

eine ältere Seite, als es die aktuelle Website noch nicht gab:

http://forum.iobroker.net/viewtopic.php … 7997#p7995

Sorry nochmal für die kurze "Abfuhr" vorhin. ich hatte wirklich gedacht die Seiten seien schnell zu finden. Selbst ich habe mich da schwer getan und noch nicht mal alles gefunden was ich meinte fonden zu können :(

Gruß

Rainer

kmxak

Wenn ihr Hilfe benötigt schreibt doch eine Liste ins Forum.

Ich könnte die Anleitungen/Doku… Anfänger technisch Analysieren und bei Verständnisproblemen Rückmeldung geben.

Infos zusammentragen. / Lösungen aus dem Forum Dokumentieren oder so.

Wiki ist manchman schon praktisch.

thobastian

Hallo Zusammen,

also ich glaube, hier könnte echt was Interessantes entstehen.

Um mal zu verdeutlichen, was ich meine, hier mal eine Idee, wie wir eine gute Dokumentation eines Adapters bekommen.

Grundgerüst könnte z.B. Adapter "history" sein. So sieht die Imhaltspunkte aus:

Steckbrief (Version,Voraussetzungen,Entwickler,Stichworte,Guthub,Plattform,License)
Konfiguration (div.Einstellungen)
Bedienung (Anleitungen, Videos usw)

weitere mögliche Punkte:

Beispiele

So gut dokumentiert, wie der Adapter History sind leider die wenigsten Adapter. z.B. der YAHA (Yet another Homekit adapter). Das hat seine Gründe.

Der Homekit Adapter hat bei mir nicht funktioniert und ich suchte nach Alternativen. Dabei fand ich YAHA. hier das Froum:

http://forum.iobroker.net/viewtopic.php?f=23&t=4136.

Dort konnte mir u.a. Dutchman helfen.

Aber für mich ist es nun nach der Lösung meines Problems wichtig, die Erkenntnisse zu sichern. Dutchman hat sogar ein Erklär-Video gedreht! :idea:

Das finde ich wirklich schade, wenn da im Forum "vergammelt". Sorry, aber das wird es, wenn die schönen Beispiele von Dutchman UND das Video nicht in die Beschreibung gesichert werden.

Es ist als Anfänger sehr schwierig im Forum zu suchen. Das gilt für alle Foren. Nicht nur hier.

Die Dokumentation muss ja kein Wiki sein, aber beim Wiki gefällt mir, dass jeder die Doku erweitern kann.

Natürlich ist der Grad der Pflege immer abhängig von Personen, Sichtweisen usw. Das kann man sowieso nicht ausmerzen. Es gibt ja keine Doku-Pflicht. (zum Glück!).

Aber wenn hier die Doku immer weiter aufgebohrt wird & aktuell gehalten wird, sind wir ein gutes Stück weiter.

Vorteile:

Verweis in den Foren auf wiederkehrende Fragen per Link
viel mehr zufriedene User (Auch User, die keine Entwickler sind, wie ich)
in der Entwicklung befindene Adapter werden öffentlicher

etc..

nächste Schritte wären:

Festlegen, welche Oberpunkte in die Beschreibung sollen (siehe oben)
wer macht was?
Adaptermenü besser strukturieren (Adapter aus Startseite entfernen, Beginnertutorial für Homematic und Raspi-User schreiben)

weitere Ideen? oder was meint ihr?

Gruß

Thomas

Homoran

Wie ich bereits schrieb sind nur wenige Adapterdokus wirklich fertig, obwohl selbst das mit Bluefox' rasanten Entwicklungstempo fraglich ist ;-)

Admin (mit allen seinen Reitern)
hm-rps
hm-rega
vis
flot
History
SQL
influxDB

alle weiteren Dokus sind teilweise 2-3 Jahre alt, wenn überhaupt vorhanden.

Die weitere Aktualisierung ist im Moment "on hold" weil sie alle in ein neues Format übertragen werden für die neue Website, die auf dem Usertreffen in Kassel vorgestellt wurde.

(die Frage nach dem YAHKA-Adapter bitte in separatem Thread stellen!)

Gruß

Rainer

apollon77

Hey All,

ich habe auch nach einigen Gesprächen nochmals nachgedacht.

Im aktuellen Stand ist die GitHub README.md zum Adapter die Haupt-Doku für die meisten Adapter. Einige finden "Github zu technisch", aber das liegt nur daran wie die Entwickler (meistens) dokumentieren :-( Fakt ist: Die Github README - bzw eine vom Entwickler definierte Datei/Link - ist die Doku die im Admin beim Fragezeichen hinter dem Adapter verlinkt ist.

Weil die Doku meist sehr rudimentär ist erstellt Homoran für die wichtigen Adapter noch zusätzliche Doku auf der Webseite. Aber zu erwarten oder anzunehmen das das jemals alles umfassen wird und kann ist das eher Zusatz.

Die Idee mit der neuen Webseite ist das jeder Adapter seine Webseiten-Doku selbst enthält und zur Webseite beisteuert. Die Webseite ist also noch nicht da.

Daher hier meine Meinung wenn man als User für einen Adapter Doku beisteuern oder verbessern will:

Kurzfristig:
zum Github Projekt des Adapters gehen (web)
README.md als File anklicken
Stift Icon = Edit
Änderungen einbauen
Unten dann Name und kurze beshreibung der Änderung und dann "propose change" klicken

Mittelfristig wenn alle Adapter-Dokus im Adapter sind … geht das per Webseite :-)

Jeeper.at

Der folgende Thread ist ein klasse Beispiel warum einerseits ein Anfänger nichts findet, und warum manche Probleme nicht gelöst werden.

http://forum.iobroker.net/viewtopic.php?t=6325#p65179

Der Thread ist als gelöst gekennzeichnet, trotzdem wird ein neues Problem drangefügt.

Da er gelöst wurde, warum sollte ich als Entwickler dann noch reinschauen.

Nochmal mein Vorschlag solche Threads zu schließen und schon hat man ein Suchbereiche Nachschlagewerk

Lg

Günther

aleks-83

Ich frage mich immer wieder wo ich die WIKIs oder DOKUs zu den Adaptern finde.
Als Link im Adapter wird man auf die GitHub Seite geleitet.
Dort steht oft nicht viel drin.

Dann erstellt man hier im Forum einen Thread mit einer Frage und wird angepflaumt warum man denn die Adapter Doku nicht gelesen hat.
Wenn dort aber nicht viel steht, kann ich ja nicht wissen wir es funktioniert!?

Beispiel hue Adapter: Was bedeutet "natives Ein-/Ausschaltverhalten" oder "Legacy-Struktur"?

Jey Cee

@aleks-83 Die Böse Antwort: Das Forum ist die Dokumentation.
Hier schreiben unglaublich viele, teils wirklich super sachen. Davon könnte man locker einiges 1:1 in die Doku übernehmen, wobei die erste Anlaufstelle dann in jedem fall Github wäre. Und genau das ist das Problem, zu wenige erstellen Pull Requests mit ihren Beschreibungen.
Neben der Entwicklung bleibt halt dann auch noch die Doku an den Entwicklern hängen. Und sind wir mal ehrlich eine gute Doku zu schreiben ist mindestens genau so schwierig wie einen Adapter zu Entwickeln.
Aus Entwickler sicht gibt es dazu noch ein Problem, man selbst versteht ja wie man einen Adapter benutzen muss und sieht vieles auch gar nicht.

BBTown

@aleks-83 sagte in Dokumentation / WIKI - Diskussion:

Beispiel hue Adapter: Was bedeutet "natives Ein-/Ausschaltverhalten" oder "Legacy-Struktur"?

hier hast Du gerade zwei Funktionen bzw. Einstellungen erwischt, die brandneu sind und daher ggf. noch nicht in ein DOKU oder auf GitHub eingeflossen sind.

Natives Ein-/Ausschalten siehe hier

Legacy-Struktur: der HUE-Adapter in der v2.x.x legt die Datenpunkte etwas anders an, als die v1.x.x. Setzt man diesen Haken, dann wird die ursprüngliche Struktur (sofern jemand bereits die v1.x.x im Einsatz hatte) nicht angetastet bzw. bleibt erhalten.

foxriver76

@aleks-83 Steht doch alles hier anpflaum

Wenn man empfindet, dass nötige Dokumentation in der Readme fehlt, darf man auch gerne ein Issue erstellen um mich darauf aufmerksam zu machen. Denke die meisten Entwickler haben da nichts gegen. ;-)

aleks-83

Hey, Danke für eure Rückmeldungen.

Versteht mich nicht falsch...
Ich wollte niemande direkt ansprechen oder an den Pranger stellen sondern allgemein auf die Adapter Dokumentationen aufmerksam machen.

Ich kann mir auch vorstellen dass das Erstellen und Pflegen eines Adapters schon viel Zeit erfordert und dass dann die Zeit für eine Doku fehlt. Den Aufwand weiß ich auch auf jeden Fall zu schätzen. Habe großen Respekt davor.

@foxriver76 sagte in Dokumentation / WIKI - Diskussion:

@aleks-83 Steht doch alles hier

Seit wann denn das?
Ich war vorhin noch auf der Seite, da stand es noch nicht.
Oder war ich auf einer alten Seite?
Dort stand oben dick "moved to ... (internet Link zu GitHub)
Wenn man drauf geklickt hat, kam man wieder auf die gleiche Seite.

foxriver76

@aleks-83 sagte in Dokumentation / WIKI - Diskussion:

Seit wann denn das?
Ich war vorhin noch auf der Seite, da stand es noch nicht.
Oder war ich auf einer alten Seite?
Dort stand oben dick "moved to ... (internet Link zu GitHub)
Wenn man drauf geklickt hat, kam man wieder auf die gleiche Seite.

Habe es aufgrund deines Hinweises eingepflegt.

aleks-83

Vielen Dank.

Schnell und informativ !

Community Forum

NEWS

Dokumentation / WIKI - Diskussion

Support us

549

32.8k

82.8k

1.3m