Erfahrungen mit Dokumentation (am Beispiel SQL-Adapter)
-
Da sind wir auf der selben Wellenlänge. Vor 8 Wochen habe ich auch noch nichts vom ioBroker gewusst.
Ich bin der Auffassung, das es einen Stype-Guide für Entwickler geben muss. Z.B für den Design des User-Interfaces.
Vgl. viewtopic.php?f=20&t=15403
Das ist etwas mehr als ein technisches Template für die Erstellung eines Adapters. Adapter sollten, wenn sie eine gewisse Reife erreicht haben, in einer zentralen offiziellen Dokumentation aufgenommen werden. Diese Dokumentation muss wiederum dem Style-Guide entsprechen. Sie muss gepflegt werden, damit z.B. neue Erkenntnisse aus dem Forum dort einfließen. Vernünftige Vorgehensweisen und Paramterbeschreibung auch für Anfänger sind ein Muss. Soll die Doku in Wiki-Form sein, damit viele daran arbeiten können? Muttersprachler für Übersetzungen wären toll. Admin-UI: Tooltipps sind eine Methode. Dynamische Links für Eingabenfelder auf die Doku mit genauer Paramterbeschreibung eine weitere (und im Zweifel aktueller, da unabhängig vom Adapter updatebar).
Dann bleibt noch offen, wie mit Adaptern umgegangen werden soll, deren Entwickler sich aus der Entwicklung zurückgezogen haben oder denen das UI einfach egal ist? Was ist, wenn da eine UI-Text immer wieder zu Missverständnissen führt? Reicht da eine Dokumentation?
Ich halte den stark dezentralisierten Ansatz zur Adaptererstellung für einen der größten Stärken des ioBrokers. Neue Adapter mit tollen Funktionen erwachsen daraus. Aber er kann auch zur jetzigen Situation führen, wo im Zweifel viel zu wenig, zersplittert oder für den Endanwender unverständlich dokumentiert ist. Es steckt eben keine Firma mit entsprechenden Ressourcen dahinter.
-
Hi ManfredH,
wie Du sicher bei den anderen Antworten zwischen den Zeilen lesen kannst ist das Thema Doku ein "Wunder Punkt".
Ideen es zu lösen gibt es, die Ressourcen und zeit sind ein anderes Thema. Und die Mehrsprachigkeit der bisherigen Ansätze (Deutsch,Englisch, Russisch, Admin noch X weitere europäische Sprachen) erledigt Ihr übriges.
Der grobe Plan ist schon länger das Adapter Ihre Doku mitbringen. Im April haben wir dazu in Kassel beim Treffen grob besprochen wie es laufen soll. Das muss man jetzt angehen, deswegen sag ich mal noch nicht so viel über die Details.
Weitere Themen sind Entwickler dazu zu ermutigen End-Nutzer-freundliche Doku zu schreiben, am Ende darf Doku die Weiterentwicklung nicht aufhalten und und und.
Alles in allem ein sehr spannendes Themenfeld, wo wir auf die Unterstützung der Community zählen werden. jeder auch noch so kleine Beitrag (sei es ein FAQ-Beitrag(Eintrag oder korrekturen an Doku) wird in Zukunft möglich und nötig sein. Das Thema ist nur zusammen zu stämmen!
Ingo
-
Und die Mehrsprachigkeit der bisherigen Ansätze (Deutsch,Englisch, Russisch, Admin noch X weitere europäische Sprachen) erledigt Ihr übriges. ` Kenn ich - hab schon vor über 30 Jahren Software internationisiert
> jeder auch noch so kleine Beitrag (sei es ein FAQ-Beitrag(Eintrag oder korrekturen an Doku) wird in Zukunft möglich und nötig sein.
Auch diese "kleinen Beiträge" stehen und fallen mit der Umsetzung. Wenn ich als Anweder/Kontributor den Eindruck habe daß meine Vorschläge im Sande verlaufen, weil der Zuständige dafür entweder keine Zeit hat (haben will) und weil's ihm sonstwo vorbeigeht, dann werd ich mir Vorschläge ganz schnell sparen. Eine Community lebt dann, wenn nicht nur viele diskutieren, sondern wenn auch was passiert. Kann ich als langjähriger Admin eines Forums nur betonen. -
Als gaaanz kurzer Abriss:
Ja Github ist der Platz zum Entwickeln. Er ist aber auch der Platz wo alles zu den Adaptern liegt (code und Bilder und so).
Die ganz grobe Idee ist:
Jeder Adapter hat seine Doku im Verzeichnis "docs" in seinem Github. Idealerweise eine allgemeinverständliche End-Nutzer-gerichtete Seite und gern FAQs, oder auch Expertenseiten. Auf jeden Fall aber schon hier eine Trennung zwischen Zielgruppen.
Das ganze als MD Dokumente und alle Bilder auch dort und so. SO kann jeder User hier auf Github editieren und Pull-Requests einreichen.
Weiterhin gibt es ein "iobroker.docs" Projekt wo die "Nicht adapter-spezifische" Doku drin gleicher Forum drin ist.
Das alles wird dann genommen und daraus zusammen "der Doku-Teil der Webseite" gebaut einmal am Tag oder so.
Details stimmen wir gerade ab. Also stay tuned
-
SO kann jeder User hier auf Github editieren und Pull-Requests einreichen. `
Was dann wieder voraussetzt, daß man sich auf github a) registriert und - vor allem - b) mit der Mimik dort auch auseinandersetzt. Dafür sollte es dann zumindest auch eine Anleitung geben. -
Jeder Adapter hat seine Doku im Verzeichnis "docs" in seinem Github. Idealerweise eine allgemeinverständliche End-Nutzer-gerichtete Seite und gern FAQs, oder auch Expertenseiten. Auf jeden Fall aber schon hier eine Trennung zwischen Zielgruppen.
Das ganze als MD Dokumente und alle Bilder auch dort und so. SO kann jeder User hier auf Github editieren und Pull-Requests einreichen. `
Zur Ergänzung: GitHub bietet an, aus dem docs-Ordner (oder anderen, wenn konfiguriert), automatisch eine gehostete Seite zu erstellen (Github pages).
https://guides.github.com/features/pages/
So kann das Hosting der Anleitungen direkt auf Github erfolgen. Der User schaut nur an, der Entwickler kann bearbeiten und PRs erstellen.
Wunschtraum: Vielleicht sogar ein ioBroker-flavored Template hierfür?
-
Jedes Ding hat aber mindestens zwei Seiten
Ich habe immer angeboten, dass ich jede Doku auch in unformatiertem text (z.B. per PN) annehme und in die Doku einbaue.
Trotz mehrfachem Aufruf ist da nur gaaaanz wenig gekommen.
Leider hat sich herausgestellt, dass solche Gastbeiträge, die ich z.B. mangels Hardware nicht testen konnte irgendwannim Forum zerrissen wurde, dass dies vorn und hinten nicht passt und nichts funktioniert - Watt Nu?
Zu guter Letzt muss ich weiterhin zugeben, dass wir mit der Idee die Website/Doku umzugestalten schon sehr lange schwanger gehen, und es immer wieder an anderen Dingen hängt.
Leider haben wir uns damals (aus verschiedenen Gründen) entschieden an der bestehenden Doku nichts mehr zu ändern, in dem Glauben, dass die neue wesentlich schneller online sei.
Github pages) `
Das ist/war eine der OptionenGruß
Rainer
-
Leider hat sich herausgestellt, dass solche Gastbeiträge, die ich z.B. mangels Hardware nicht testen konnte irgendwannim Forum zerrissen wurde, dass dies vorn und hinten nicht passt und nichts funktioniert - Watt Nu? `
Geht's nur um die Doku? Oder auch das UI?Meine Meinung: Es ist zwar ehrenwert, wenn jemand einen Adapter schreibt (meist weil er ihn selbst braucht). Die Frage ist dann, ob man diesen Adapter dann der Allgemeinheit "zum Fraß vorwirf". Da geht's nämlich los mit der Qualitätskontrolle. Entweder man ist drauf aus, möglichst viele Adapter anzubieten (Quantität), weil man glaubt, daß eine möglichst breite Basis dem ioBroker hilft, oder man schaut auf die Qualität und lehnt Adapter, die bzgl. UI und Doku den (natürich) gesetzten Standards nicht entsprichen, ab; ob ein Adapter in die Liste aufgenommen wird obliegt ja den Administratoren. Natürlich kann jeder sein Werk auf github veröffentlichen (und auch bewerben), aber das ist dann schon alles. Wenn der Entwickler zeigt, daß er sich um sein Werk kümmert, im Forum antwortet und die gemeldeten Bugs anpaßt, dann kann man den dann ja irgendwann in die offizielle Liste wieder aufnehmen.
> Zu guter Letzt muss ich weiterhin zugeben, dass wir mit der Idee die Website/Doku umzugestalten schon sehr lange schwanger gehen, und es immer wieder an anderen Dingen hängt.Also ich für meinen Teil finde die Seite eigentlich übersichtlich (und gut) genug. Leider halt unvollständig und teilw. veraltet.> Leider haben wir uns damals (aus verschiedenen Gründen) entschieden an der bestehenden Doku nichts mehr zu ändern, in dem Glauben, dass die neue wesentlich schneller online sei. :(Und in der Zwischenzeit hängen potentielle Anwender in der Luft (so wie ich). Ich kenn die Hintergründe der diversen Aktionen (z.B. Admin 3) zwar nicht, aber man muß sich halt überlegen, was irgendwelche tollen Sachen auf der einen Seite bringen, wenn auf der anderen die Anwender frustriert sind und dem ioBroker den Rücken kehren (sprich mit den Füßen abstimmen) - da ist auch nix gewonnen. Aber wie ich sehe, bestätigt sich meine langjährige Erfahrung, daß die Doku selten wirklich wichtig genommen wird und Vorrang vor anderen Aktivitäten bekommt.
Zum Glück hab ich wenigsten rudimentär Ahnung und i.d.R. auch die Zeit, mich mit den Unzulänglichkeiten auseinanderzusetzen, auch wenn's manchmal wirklich nervt (wie der 3-malige komplette Neustart meines Projekt aufgrund der Inkompatibilität des npm).
-
ob ein Adapter in die Liste aufgenommen wird obliegt ja den Administratoren. `
Nachtrag: aus meiner Projektleiterzeit kenne ich das Vorgehen, eine neue Software erst einmal zu pilotieren. In dem Fall würde das bedeuten, daß ein neuer Adapter erstmal einen "Beta"-Status bekommt für einen gewissen Zeitraum. Werden die Bugs/Unzulänglichkeiten behoben, gibt's schließlich die Aufnahme in die offizielle Liste. Wenn nicht, dann bleibt der Adapter halt im Beta-Status und fliegt irgendwann ganz raus. -
Und da gebe ich dir vollkommen recht:
@ManfredH:Und in der Zwischenzeit hängen potentielle Anwender in der Luft `
und das missfällt mir wahrscheinlich sogar mehr als dir, weil ich weiss wo es überall brennt.daß die Doku selten wirklich wichtig genommen wird und Vorrang vor anderen Aktivitäten bekommt. `
Dem hingegen möchte ich so vehement widersprechen wie es nur geht.In diesem Fall hängt es an der Basis , sozusagen an dem Behälter, in den die Doku als Inhalt gebracht werden soll.
Gruß
Rainer
