Vorschlag für Verbesserungen der Dokumentation

[NetFritz]

Hallo

@peuter
1. In der Sourcecode Doku wird ja, wie der Name schon sagt, der Sourcecode dokumentiert, also die Klassen und deren Methoden beschrieben.
2. Die Widget-Beispiele gehören nach diesem Verständnis streng genommen auch gar nicht da rein.

Damit hast Du mit deinen Beispielen mich aufs Glatteis geführt.
Ich habe das so aufgenommen das das auch als Nachschlagewert für den Anwender dient,
denn diese Infos sind auch für den Anwender nützlich.

@Chris M
Aber ich hab die Doku lieber in reinem Englisch als gar keine

Da gebe ich Dir vollkommen Recht.

Gruß NetFritz

[peuter]

Ich habe das so aufgenommen das das auch als Nachschlagewert für den Anwender dient,
denn diese Infos sind auch für den Anwender nützlich.

Ja klar, nur soll sie der Anwender halt nicht an der Stelle finden sondern im (noch in dieser Form zu erstellenden) User Manual.

[peuter]

Ich hab den Pullrequest hierfür jetzt mal gestellt, die Dokumentation der Widgets ist zwar noch nicht vollständig (ca. die Hälfte fehlt noch komplett, beim Rest könnte es teilweise mehr ins Detail gehen und vielleicht auch noch das ein oder andere Beispiel vertragen), aber die Grundlagen sind gelegt, es gibt genug Beispiele wo man sich abschauen kann wie es gemacht werden kann/sollte und das Changeset ist jetzt schon gewaltig.

Daher sollte der erstmal reviewed und irgendwann gemerged werden und dann kann man den Rest in Angriff nehmen. Vor allem kann und will ich das nicht alles alleine Dokumentieren. Bei den Unittest ist das schon keine gute Sache, dass ich da relativ alleine an dieser Front kämpfe, denn ich hab z.B. beim Infotrigger den Test anhand meines Verständnisses des Codes geschrieben (da ich den Infotrigger weder programmiert noch jemals benutzt habe, ist das die einzige Möglichkeit). Problem war nur, dass der Code falsch war somit hatten wir einen Test der falsche Dinge testet und sagt die Welt ist in Ordnung, was zumindest für die Funktion, dass man im Infotrigger Bilder durch horchen auf eine Gruppenadresse ein/-ausblenden und sogar ändern kann, absolut falsch war. Das ging nämlich gar nicht.

[Wurschtel]

Das ist alles total spannend zu verfolgen .... ich denke, daß Anwenderprofile wie meines im ersten Schritt im Browser "www.cometvisu.org" eingeben, dort den Link "Benutzerhandbuch" finden, drauf klicken ..... und schon geht das oft nicht zielführende Im-Kreis-herumsuchen los.

Ist es das, was ihr mir all dem oben Gesagten meint?

[Chris M.]

Nein, nicht ganz. Was Du beschreibst ist dem geschuldet, dass wir ein Wiki für eine Doku missbrauchen.

Ein Wiki lebt davon, dass man immer im Kreis herum kommt. Bei einer Enzyklopädie wie Wikipedia ist das ein sehr schöner Effekt, man lernt immer neues dazu während man vom hundertsten ins tausende kommt.

Eine gute Doku ist strukturiert aufgebaut, man fängt oben an und liest bis unten durch und weiß dann ungefähr was Sache ist.

Ein besseres System wo Nicht-Programmierer sich an der Doku beteiligen können ist mir jedoch aktuell nicht bekannt (hier gehören viel mehr Abwägungen dazu als das erst beste Google Ergebnis zu postulieren).
Was wir hier diskutieren ist unabhängig davon zu sehen: es geht darum den Code besser zu dokumentieren. So dass Nicht-Programmierer, die sich an der Doku beteiligen wollen, besser verstehen, was in die Doku rein soll, bzw. technisch korrekt ist.

[Chris M.]

Ich hab den Pullrequest hierfür jetzt mal gestellt, die Dokumentation der Widgets ist zwar noch nicht vollständig (ca. die Hälfte fehlt noch komplett, beim Rest könnte es teilweise mehr ins Detail gehen und vielleicht auch noch das ein oder andere Beispiel vertragen), aber die Grundlagen sind gelegt, es gibt genug Beispiele wo man sich abschauen kann wie es gemacht werden kann/sollte und das Changeset ist jetzt schon gewaltig.

Ich sehe es auch als Sinnvoll an, erst mal die Grundlagen mit entsprechenden Beispielen einzubauen und dann den Rest zu befähigen. Am konkreten Beispiel diskutiert es sich einfacher.

Vor allem kann und will ich das nicht alles alleine Dokumentieren. Bei den Unittest ist das schon keine gute Sache, dass ich da relativ alleine an dieser Front kämpfe,

Alleine zu Kämpfen ist meist frustrierend. Ich helfe gerne bei meinem Code mit, habe aber gerade ein paar Dinge, die mir unter den Nägeln brennen (insb. "ceramic"), so dass ich hier aktuell nur wenig machen kann. Es ist aber jeder andere auch eingeladen zu helfen - und sowohl beim Unit-Test schreiben als auch beim Code selbstdokumentieren kann man gut in die Code Struktur hinein kommen

[Wurschtel]

Wenn unter "der guten Doku" etwas ähnliches wie das oben genannte Benutzerhandbuch verstanden werden soll, könnte ich mir durchaus vorstellen, mir auf der Basis des Vorhandenen eine anwenderbezogene Struktur zu überlegen. Im großen und Ganzen ist die ja schon okay .... auf meiner eigenen Liste sind aber noch einige Fragezeichen, die ihren Platz in der Beschreibung suchen.

Sobald es jedoch in Code- oder Programmiespezifisches geht, bin ich außen vor.

[peuter]

Wenn unter "der guten Doku" etwas ähnliches wie das oben genannte Benutzerhandbuch verstanden werden soll, könnte ich mir durchaus vorstellen, mir auf der Basis des Vorhandenen eine anwenderbezogene Struktur zu überlegen.

Das wäre wirklich hilfreich, ich bastele gerade nämlich daran den "Dokumentateuren" das Leben ein wenig leichter zu machen (hoffentlich). Irgendwann in naher Zukunft müssten dann die Inhalte aus dem Wiki nach und nach übertragen werden und da wäre es sinnvoll sich vorher zu überlegen, ob man an der vorhandenen Struktur den etwas verbessern kann.

Der aktuelle Stand der Dinge ist aus dem angehängten Screenshot zu entnehmen. Inhaltlich ist das im Wesentlichen das was im Wiki zum Switchwidget steht. Der Unterschied ist, dass alle Bilder automatisch erzeugt werden. Auch die Attribute und Elementbeschreibungen (die sind noch nicht fertig wie man sieht) werden vollautomatisch aus der XSD-Datei generiert. Das sind also alles Dinge, die automatisch erzeugt und aktuell gehalten werden.

Was jetzt eventuell ein Nachteil ist, weil es eben ein wenig Einarbeitung erfordert, ist das man die Syntax in der die Dokumentation geschrieben wird erstmal ein wenig lernen muss (ist aber nicht allzu kompliziert), aber beim Wiki ist das ja nicht anders. Jetzt ist es halt reStructuredText (https://de.wikipedia.org/wiki/ReStructuredText).
cometvisu_doc_manual_de_html_widgets_switch_.png

[SirTobiIV]

Ich finde das Beispiel fast vorbildlich dokumentiert.
Ich habe ja vor einiger Zeit mal etwas mit der visu gespielt und habe eher durch trial and error gelernt

Aus meiner Sicht sind drei Dinge ganz elementar:
1. Grobe Beschreibung was das Ding überhaupt macht bzw. Wozu es verwendet werden kann.
2. Minimal XML Konfiguration, damit das Teil fehlerfrei funktioniert.
3. Beschreibung zu jedem!! Parameter. Viele sind leider nicht selbsterklärend.

Beispiele und Screenshots sind für mich eher die Kür als notwendig.

[Wurschtel]

Das Beispiel von peuter sieht ja schon superklasseperfekt aus und die drei Anmerkungen von SirTobilV stellen nach meinem Dafürhalten schon fast des Pudels Kern dar.

Zu Punkt 1 (Grobe Beschreibung) habe ich gerade eben drei rudimentäre Zeilen getippt, die so ungefähr den meiner Meinung nach notwendigen Tiefgang für Anwender darstellen könnten .... also mal eben ganz grob im Sinne von "to be discussed and continued":

CometVisu ist eine Visualisierungslösung für die Hausautomation. Zum Betrieb von CometVisu wird ein Webserver benötigt, welcher das Layout und die Inhalte zur Darstellung in üblichen Webbrowsern liefert.

Im Gegensatz zu üblichen Client-Anfragen, bei denen durch Clients Verbindungen zum Server hergestellt werden, welcher dann die Anfrage bearbeitet, die Antwort generiert und sendet und danach die Verbindung wieder schließt, erfolgt die Kommuniktion mit Comet-Technik genau umgekehrt. Sobald es angezeigt ist – sich also eine mitzuteilende Zustandsänderung einstellt - wird die Verbindung vom Server hergestellt und die Änderung an den Client gesendet. Diese umgekehrte Vorgensweise stellt eine echtzeitaktuelle Darstellung innerhalb von CometVisu sicher.

CometVisu schaltet, regelt oder steuert nicht selbst. Mit CometVisu werden im Grunde genommen nur „ausgelesene Zustände“ dargestellt und „gewünschte Zustandsänderungen“ weitergegeben. CometVisu ist somit ein sogenanntes „frontend“.

Das eigentliche Schalten und Walten wird von „backends“ bewerkstelligt. Die Abgrenzungen zwischen den einzelnen backends sind etwas fließend.
Im einfachsten Fall handelt es um ein reines deamon-Tool (eibd resp. knxd), welches die Verbindung zwischen dem Telegrammverkehr in drahtgebundenen oder funkbasierten Infrastrukturen einer KNX-basierten Hausautomation und CometVisu herstellt und von CometVisu empfangene „gewünschte Zustandsänderungen“ wiederum in deren Telegrammverkehr einreiht.
Ein weiteres, äußerst ausbaufähiges backend ist openHAB. Neben der Einbindung weiterer Kommunikationsprotokolle wie eocean oder 1wire können innerhalb von openHAB Regeln und Logiken formuliert werden.

[peuter]

Im Gegensatz zu üblichen Client-Anfragen, bei denen durch Clients Verbindungen zum Server hergestellt werden, welcher dann die Anfrage bearbeitet, die Antwort generiert und sendet und danach die Verbindung wieder schließt, erfolgt die Kommuniktion mit Comet-Technik genau umgekehrt. Sobald es angezeigt ist – sich also eine mitzuteilende Zustandsänderung einstellt - wird die Verbindung vom Server hergestellt und die Änderung an den Client gesendet.

Das ist so nicht korrekt. Der Server kann selbstständig keine Verbindung zum Client herstellen. Das funktioniert so, dass der Client eine dauerhafte Verbindung zum Server aufbaut auf der der Server dann Daten an den Client senden kann (wenn mans ganz genau nimmt gibts hier 2 Varianten: Beim 'long-polling' wird die Verbindung geschlossen wenn der Server Daten geschickt hat und danach vom Client sofort wieder aufgebaut und bei 'Server sent events' bleibt die Verbindung dauerhaft bestehen. Aber das sind für den normalen Anwender sicherlich zu viele Details).

Da das mit den Screenshots auf Dauer etwas mühsam ist, gibts hier den aktuellen Stand des Benutzerhandbuchs (momentan muss ich das noch von Hand aktualisieren, also wird das nicht immer die top-aktuellste Version sein, aber ich bemühe mich das einigermaßen aktuell zu halten, und irgendwann wird auch das automatisiert, damit das mit jedem commit aktualisiert wird):

http://peuter.github.io/CometVisu/de/index.html

Ich bitte zu beachten, dass dort nur die Startseite des Wiki-Handbuchs übernommen wurde. Das Switch-Widget habe ich mal Beispielhaft einigermaßen komplettiert (mit einer Mischung aus Daten aus dem Wiki und automatisch generierten). Alle anderen Widgets-Seiten sind von einem Skript automatisch erzeugt worden und dementsprechend haben die nur die Grundstruktur, Beispiele sind entweder unvollständig oder Fehlerhaft. Alles weitere fehlt komplett.

Geht auch wie gesagt erstmal darum am Beispiel des Switch-Widgets festzuklopfen, was wir alles in welcher Struktur dokumentiert haben möchten und dieses dann auf die anderen Widgets zu übertragen.

[Wurschtel]

Hallo ...

ich habe jetzt gerade eben mal auf deinen Link geklickt .... der Aufbau ist ja genial!

Dass mein kleiner Textbeitrag nicht fehlerfrei ist, habe ich fast erwartet. Ich tippe mit dem Wissen eines Anwenders und "male mir die Welt, so wie ich sie will". You see?
Also .... ein kritisches Gegenlesen ist unbedingt erforderlich.
Ich habe mich auch bewußt etwas umgangssprachlich ausgedrückt, da ich mal davon ausgehe, daß die meisten mit einem meinem Wissensstand vergleichbaren Background an CV herangehen.

Wenn es also gewünscht ist, kann ich gern hin und wieder mal versuchen, meine Gedankengänge in Worte zu fassen.

[peuter]

Kleines Update: die Links haben sich geändert:

Benutzerhandbuch:
http://peuter.github.io/CometVisu/de/manual/

Sourcecode-Doku:
http://peuter.github.io/CometVisu/api

Aber dafür wirds bei jedem Commit automatisch aktualisiert ;-)

[NetFritz]

Hallo
Echt Spitze.
Gruß NetFritz

[SirTobiIV]

Ich nehme am, wenn du nun noch erklären würdest, wie sich jeder einfach an der Vervollständigung der Doku beteiligen kann, werden sich sicherlich einige finden, die gerne helfen würden.

Siehe zum Beispiel meinen aktuellen Kampf mit den beiden überhaupt nicht dokumentierten widgets navbar und pagejump.