Vorschlag für Verbesserungen der Dokumentation

[peuter]

Ich möchte hier mal einen Vorschlag zu Diskussion stellen, der aus meiner Sicht mal in Betracht gezogen werden könnte damit der Entwicklungsstand und der Dokumentationsstand der CometVisu in Zukunft einigermaßen synchronisiert werden.

Es gibt Dienste wie z.B. readthedocs.com die Dokumentationen in verschiedenen Versionen + Sprachen für Projekte hosten. Zusammen mit der vorhandenen Github Intergration könnte man mit ein wenig Fleißarbeit das Ganze soweit automatisieren, dass man immer eine aktuelle Doku von allen zukünftigen Releases inkl. des Entwicklungszweigs hat. Ich habe das Ganze selbst zwar noch nicht benutzt aber was man auf deren Seite so lesen kann hört sich ganz vielversprechend an.

Dazu müsste allerdings mal die vorhandene Doku als restructuredText-Format mit ins Github-Repo transferiert werden. Dann könnte man in Zukunft PRs für neue Features z.B. nur noch mit Dokumentation akzeptieren, denn jeder Entwickler sollte in der Lage sein zu beschreiben was er da so gebaut hat.

Ich denke für Nicht-Entwickler wäre die Einstiegshürde im Vergleich zum aktuellen Wiki auch nicht viel höher. Zugangsdaten braucht man für beides. Textdateien kann man auch auf Github direkt bearbeiten, wenn man sich das clonen sparen möchten (gut ist vermutlich nicht ganz zu einfach wie eine Seite im Wiki zu ändern, aber immer noch zumutbar).

Sicherlich wäre das einmalig ein größerer Aufwand alles soweit einzurichten und zu portieren, aber aus meiner Sicht wäre es die Mühe wert. Wie seht Ihr das, gibts hier vielleicht sogar jemanden der Erfahrungen mit readthedocs hat und ein paar Tipps geben könnte?

[Chris M.]

Erfahrungen damit habe ich nicht (ich kenne den Dienst nicht einmal...)

Was mir aber schon länger vorschwebt, ist in den einzelnen Widget-Source-Dateien die notwendige Doku für dieses jeweilige Widget mit unter zu bringen. So sollte der wesentlichste Teil der Doku (genauer: Referenz) sich vergleichsweise leicht Up to Date halten zu sein.

Daneben gibt es natürlich noch einiges an wirklicher Doku, die z.B. für einen Einstieg absolut notwendig ist (vergleichbar einem Tutorial). Das sollte v.a. von Nicht-Programmierer leicht zu pflegen sein - hier tuen sich die Programmierer beim schreiben am schwersten, da es eine gänzlich andere Sicht auf das Programm benötigt.

Das (aktuelle) MediaWiki ist nur ein Versuch um die Doku möglichst schmerzfrei erstellen zu können. Das es nicht 100% optimal ist, war von Anfang an klar - ich kannte nur nichts besseres. Inzwischen ist mir klar, dass wir weit weg sind von den 100%...

Wesentlich wichtiger als meine Meinung, wäre die der (potentiellen) Doku-Schreiber
swiss wenn Du wieder tiefer einsteigen kannst/magst/..., was ist z.B. Deine Meinung?

[Wurschtel]

Uiiiiiiiiiiii ... bei diesem Thema spitze ich nun aber ganz besonders die Ohren!
Ich kann mir auch gut vorstellen, daß sich manch ein anderer den Titel schon in's Abo gepackt hat.

Ob das Medium der Wahl nun das Github-Wiki oder die mir unbekannten MediaWiki oder readthedocs ist, dürfte hier wahrscheinlich verhältnismäßig egal sein (... spricht der Laie). Nach meiner Ansicht ist die konsistente Darstellung - respektive Dokumentation - des Projekts das A & O der ganzen Unterfangens. Denn ist es nicht so, daß das selbst beste "Thing" in der Versenkung verschwindet, wenn man keinen Zugang dazu findet?

Ich denke, das man als noch völlig Unbedarfter in der Sache nach einem ersten Einlesen in die Thematik den Eindruck haben muß, es verstehen zu können und sich ein Gefühl einer groben Übersicht einstellen sollte. Für Details hätte man sich dann mit den jeweiligen Unterkapiteln zu beschäftigen.

Hier würde ich eventuell sogar auf zwei unterschiedliche Zielgruppen abstellen. Zum einen der wahrscheinlich kleine Kreis der Entwickler und zum anderen die große Gruppe der "Nutznießer", also solche Kameraden, wie ich einer bin ().

Die kleine Kreis der Entwickler tauscht sich in der Regel auf paralleln Kanälen aus und spricht dort ohnehin in Geheimsprachen wie Java, Phyton, JSON usw usw miteinander. Für die Phalanx der Nutzer dürften das viele spanische Dörfer sein, die brauchen etwas Pragmatischereres. Ob für den "Erst-Einstieg" Tutorials wirklich geeignet sind, glaube ich nun weniger. Hier wäer m.E. eine etwas ausführlichere Darstellung dessen,

- was CV ist,
- wozu man CV einsetzt,
- wie CV im Umfeld von KNX/openHAB eingebunden ist und ... ganz wichtig
- wie CV aufgebaut ist

zielführender. Tutorials ergänzen dann die ganze Sache.

Ich kann jetzt hier zwar nur für mich sprechen, bei mir war es auf jeden Fall so, daß ich durch die Darstellung fertiger Beispiele Lust auf mehr bekam, mir das Einarbeiten (womit ich immer noch beschäftigt bin) ziemlich schwer fiel. Von Haus aus bin ich alles andere als nicht-technik-affin und habe sogar irgendwas mit Technik an 'ner Uni hinter mir - ich bin aber kein Programmierer.

[peuter]

Rein von der inhaltlichen Aufteilung könnte man sich an der neuen openHAB-Doku orientieren (http://docs.openhab.org), die ist aufgeteilt in:

1. Tutorials
2. User Manual
3. Developer Guide

Hauptsächlich ging es mir in diesem Thread um Punkt 2. Punkt 3. ist das was zur Zeit bereits im Github liegt und kann sicherlich auch mal überarbeitet/ergänzt werden, aber hat nicht die höchste Priorität. Tutorials sind für mich etwas, was aus der "Nicht-Entwickler" Ecke kommen sollte, denn als Entwickler schreibt man sowas einfach aus einer anderen Sichtweise und daher nicht unbedingt so verständlich für den großen Teil der Anwender.

In Sachen Dokumentation sehe ich da noch einen 4. Bereich, die von Christian schon erwähnte Dokumentation direkt im Source-Code (Referenz). Die sollte bei jedem Widget zumindest aus einer allgemeinen Beschreibung bestehen. Dazu noch welche XML-Attribute wie genutzt werden können um das Widget zu konfigurieren, ein paar Config-Beispiele (die könnte man sogar automatisiert da rausfischen und das neue Testsystem dazu missbrauchen daraus automatisch Screenshots des Widgets in dieser Konfiguration für eine weiterführende Dokumentation zu erstellen).

Das ist auch das zweite Hauptanliegen, um das es mir in diesem Thread geht => soviel wie möglich zu automatisieren. Wenn man eine ordentliche Dokumentation auf die Beine stellen möchte, braucht man auch viele Bilder. Diese dann immer manuell auf dem aktuellsten Stand zu halten ist mühsam und daher würde das viel Arbeit ersparen, wenn man z.B. Screenshots von allen Widgets in verschiedenen Ausprägungen / Sprachen / Designs automatisch erstellen würde.

Die Source-Code Dokumentation (4.) fällt ganz klar in den Bereich der Entwickler. Wenn wir uns hier auf Mindestanforderungen + Format dieser Doku einigen können (was dann wiederum in 3. dokumentiert werden muss), sollten wir die vorhandenen Widgets dementsprechend dokumentieren und neue Widgets nur noch mit vorhandener Dokumentation akzeptieren. Daraus kann man dann eine API-Referenz generieren (dabei wird der Dokumentations-Text aus dem Sourcecode gelesen, hübsch formatiert und daraus eine/mehrere HTML-Seiten generiert), die wiederum als Basis für Nicht-Entwickler zum besseren Verständnis dienen kann, welche damit dann Tutorials (1.) und/oder das User Manual (2.) schreiben bzw. ergänzen können.

[Chris M.]

Merker: Wenn man 4 angeht, dann evtl. auch die XSD per Build-Prozess (teil-)automatisieren

[mfd]

Der edomi-Entwickler macht es derzeit so, dass er die wichtigsten Informationen (Hilfe) zum Einstieg direkt mit der Software liefert. Ist für den Normalverbraucher auf jeden Fall gut und veringert die Einstiegshürde(n). Allerdings bedeutet das für den/die Entwickler sicher einiges an zusätzlichen Aufwand und muss auch je nach Softwarestand händisch angepasst werden.

help.PNG

[peuter]

Allerdings bedeutet das für den/die Entwickler sicher einiges an zusätzlichen Aufwand und muss auch je nach Softwarestand händisch angepasst werden.

Naja eigentlich nicht, wenn man die Doku mit im Github-repository hat und dafür sorgt, das die Inhaltlich auf dem aktuellen Stand des Codes ist, dann kann man beim Releasen die Doku automatisch erzeugen und mitliefern.

Irgendwie hatte mich die Idee mit den Beispielen der Widgets in der Source-Code Dokumentation nicht mehr losgelassen und wollte gleich ausprobiert werden. Ich habs dann mal prototypisch implementiert und siehe da: funktioniert ganz hervorragend. Aus folgendem Sourcecode Kommentar für das Switch-Widget:

/**
 * The switch widget shows two states (e.g. ON and OFF) and can toggle between them.
 *
 * @widget_example <meta>
 *   <caption>Default example for defining an switch widget in the configuration</caption>
 *   <screenshot name="switch_example_on">
 *    <caption>Switch turned on</caption>
 *    <data address="0/0/0">1</data>
 *   </screenshot>
 *   <screenshot name="switch_example_off">
 *    <caption>Switch turned off</caption>
 *    <data address="0/0/0">0</data>
 *   </screenshot>
 * </meta>
 * <switch>
 *   <layout colspan="3" />
 *   <label>Switch</label>
 *   <address transform="DPT:1.001" mode="readwrite">0/0/0</address>
 * </switch>
 * @module structure/pure/Switch
 * @author Christian Mayer
 * @since 2012
 */

wird automatisch diese HTML-Seite generiert:
api-shot.png

Die beiden Bilder vom Switch werden automatisch aus der Beispieldefinition erzeugt. Ich bin begeistert wie einfach das war, weil die meisten dafür benötigten Dinge bereits da waren und nur ein wenig angepasst werden mussten.

[Chris M.]

Sehr schön!

Was da spannend wäre, falls das geht, wäre eine Info einbauen zu können, ab welcher Version ein Feature vorhanden ist. Gerade bei einer Online-Doku müssen wir da aufpassen, nicht das Features aus der Git Version jemanden verwirren, der das letzte Release verwendet.

Das andere was wir schauen sollten, wäre zumindest zweispraching (Englisch und Deutsch) das wichtigste dokumentieren zu können. Einfach weil unser größter Kundenstamm deutsch spricht und sich teilweise mit Englisch etwas schwerer tut.

[peuter]

Was da spannend wäre, falls das geht, wäre eine Info einbauen zu können, ab welcher Version ein Feature vorhanden ist. Gerade bei einer Online-Doku müssen wir da aufpassen, nicht das Features aus der Git Version jemanden verwirren, der das letzte Release verwendet.

"Since" dürfte dafür sein, da steht halt jetzt nur ein Jahr drin. Eine Release-Version, seit der das drin ist wäre da wohl besser. Das jetzt genau rauszufinden dürfte relativ aufwendig sein, oder? Ggf. könnte man einfach das letzte Release aus dem dort genannten Jahr dort eintragen, bzw. das erste aus dem nächsten Jahr. Das wäre nur nicht allzu exakt, aber besser als nichts.

Das andere was wir schauen sollten, wäre zumindest zweisprachig (Englisch und Deutsch) das wichtigste dokumentieren zu können.

Bei der Sourcecode-Doku würde ich beim Englischen bleiben, ist doch eher ungewöhnlich dort zweisprachig zu dokumentieren. Ich wüsste auch nicht wie man dem Generator der daraus die HTML-Seiten baut beibringen könnte, das es hier zwei Sprachen gibt (außen einen komplett eigenen Generator zu bauen, aber das will man nicht!).

Bei Tutorials/User Manual sollte das wichtigste zumindest in englisch/deutsch vorhanden sein. Und die o.g. Beispiele mit zugeh. Screenshots können/sollten natürlich auch dort automatisch eingebunden werden (zumindest im User Manual, bei Tutorials werden vermutlich eher eigene Beispiele genutzt werden).

PS: Hab die Widget-Beispiele ein wenig verbessert, so dass die jetzt auch Stylings/Mappings unterstützen.

api-shot.png

Aus meiner Sicht wäre das jetzt soweit benutzbar, das ich einen Pull-Request daraus machen würde, es sei denn es fällt jemandem noch was nützliches ein, was fehlt?

[NetFritz]

Hallo
Ich finde diese Lösung hervorragend.

@peuter
Bei der Sourcecode-Doku würde ich beim Englischen bleiben, ist doch eher ungewöhnlich dort zweisprachig zu dokumentieren.

Diese Doku ist aber wohl in erster Linie für den Anwender gedacht und darum sollte sie in Deutsch vorhanden sein.
Gruß NetFritz

[peuter]

Diese Doku ist aber wohl in erster Linie für den Anwender gedacht und darum sollte sie in Deutsch vorhanden sein.

Nein die ist eigentlich ausschließlich für Entwickler gedacht. Der normale Anwender sollte diese eigentlich gar nicht zu Gesicht bekommen, und seine Informationen komplett aus Tutorials + User Manual beziehen (das ist natürlich der Idealfall, wenn beides in ausreichendem Umfang vorhanden ist).
Außer den Beispielen, dem ersten Satz und der "Since" Information steht da auch nichts für einen Endanwender Relevantes drin. Und genau diese Teile würde ich auch automatisiert ins User Manual übertragen, wo man sich sich dann auch mal Gedanken über die Übersetzung machen kann/sollte.

Aus meiner Sicht sollte die Sourcecode-Doku dem Entwickler beim Verständnis der Sourcen helfen und ggf. hier dann auch noch den Schreiberlingen für Tutorials / User Manual als Informationsquelle dienen.

[NetFritz]

Hallo

@peuter
Aus meiner Sicht sollte die Sourcecode-Doku dem Entwickler beim Verständnis der Sourcen helfen und ggf. hier dann auch noch den Schreiberlingen für Tutorials / User Manual als Informationsquelle dienen.

Das ist aber ein Frommer Wunsch
Leider ist aber so das fast alle Entwickler programmieren wollen, aber keiner will eine Doku verfassen.
So ist man als Anwender der auch mit einem Editor die xml erstellt immer wieder darauf angewiesen in den Code zu schauen, auch in die visu_config.xsd .
Gruß NetFritz

[peuter]

Leider ist aber so das fast alle Entwickler programmieren wollen, aber keiner will eine Doku verfassen.

Ja klar jeder Entwickler schreibt nun mal lieber Code als Doku und da die Entwicklung hier in der Freizeit als Hobby passiert, macht man nun mal tendenziell lieber das was Spass macht (kenn ich ja von mir selbst). Hier gibt es aber noch einen anderen Aspekt zu bedenken: Ein Entwickler hat nun mal eine andere Sichtweise auf die Dinge als ein Anwender und für Entwickler ist es äußerst schwer Doku zu schreiben, die für Anwender leicht verständlich ist und diesem beim Einstieg hilft. Daher wird es immer von Vorteil sein, wenn Anwender auch Doku beisteuern (was ja hier durchaus auch passiert).

Und das Problem, dass Entwickler keine Doku schreiben, möchte ich ja dadurch entschärfen, dass in Zukunft kein neuer Code ohne entsprechende Dokumentation angenommen wird. Also z.B. neue Widgets oder Plugins nur mit Doku inkl. Beispielen wie z.B. oben schon gepostet. So hat man zumindest einen Grundstock der allen Seiten beim Verständnis hilft.

Und klar ist das was ich hier vorschlage Wunschdenken, geht ja darum herauszufinden wo man hin möchte, also den Idealfall einer hervorragenden Doku und dazu die ersten Schritte zu machen. Wieweit man sich dann dem Idealfall annähern kann wird die Zeit zeigen, hier sind wir natürlich sehr auf die Hilfe der Community hier im Forum angewiesen, was die Aktualisierung/Ergänzung der vorhandenen Dokumentation anbelangt. Und wenn man hier Sachen automatisieren kann, die die Dinge erleichtern kann das ja dem ganzen Vorhaben nur zuträglich sein.

[Chris M.]

Die Source Doku (bzw. natürlich das daraus abgeleitete Dokument) hat für mich als Zielgruppe auch für den Anwender (genauer: Visu-Ersteller).
Aber eben nicht als Doku im Sinne von Wie-mache-ich-was. Sondern als klassische Referenz (Nachschlagwerk).

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

Nachtrag: Diese Referenz kann dann auch sehr gut Nicht-Programmierenden Doku-Schreibern (im Sinne von Wie-mache-ich-was) als Input dienen.

[peuter]

Aber eben nicht als Doku im Sinne von Wie-mache-ich-was. Sondern als klassische Referenz (Nachschlagwerk).

In der Sourcecode Doku wird ja, wie der Name schon sagt, der Sourcecode dokumentiert, also die Klassen und deren Methoden beschrieben. Und das sind nun mal Dinge die der Visu-Ersteller nicht wissen muss um seine Visu zu erstellen, und somit ist diese Doku für diese Zielgruppe eher verwirrend, weil dort eben Dinge drinstehen die völlig unrelevant sind.

Die Widget-Beispiele gehören nach diesem Verständnis streng genommen auch gar nicht da rein. Aber wie schon erwähnt sind die dort mit dem Hintergedanken drin, dass man z.B. neue Widgets nur akzeptiert, wenn der Entwickler auch eine Beschreibung inkl. Beispielen mit den Sourcen liefert.

Die Grundidee die ich hier verfolgen möchte ist ja folgende:

1. Entwickler liefert Code mit Doku + Beispielen (als Mindestanforderung, passenden Einträge ins User-Manual + Tutorials wären natürlich auch gerne gesehen) => Sourcecode Doku inkl. Screenshots aus Beispielen wird automatisiert erstellt
2. Die nützlichen Informationen aus der Sourcecode-Doku (Grundbeschreibung, Beispiele, Screenshots, seit wann gibts das Widget/Plugin, Author, Verweise auf Tutorials, etc.) werden ebenfalls automatisiert mit ins User Manual gepackt (zweisprachig), dieses müsste dann um die automatisiert gefüllten Inhalte mit weiteren Inhalten von Doku-Schreibern erweitert werden, bzw. von vorhandener Doku kopiert werden. Also User-Manual als Mischung aus automatisierten + manuell gepflegten Inhalten in Englisch + Deutsch.
3. Tutorials

Die Mischung aus automatisierten + manuell gepflegten Inhalten aus Punkt 2 dürfte etwas kniffelig werden. Wenn das so nicht geht, kann man immer noch die Beispiele einmal manuell ins User Manual kopieren und für dieses auch einen Mechanismus schaffen der diese Dinge erkennt und die Screenshots dann automatisch erstellt und einbindet (sollte kein Problem sein, den Mechanismus gibts ja schon, man muss sich nur ein Dokumentationsformat suchen mit dem man sowas umsetzen kann, dazu muss das User Manual aber auch mit ins Github, als externes Wiki sehe ich da keine Chance). Das ist wahrscheinlich der bessere Weg, da man damit die Option hat weitere Beispiele ins User-Manual zu packen und diesen Mechanismus genauso für Tutorials zu nutzen.

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

Nun, ist ja nicht verboten diese zu übersetzen ;-) Und vor allem fürs o.g. User Manual sollte das auch passieren, bzw. kann man hier erstmal die vorhandene Doku aus dem Wiki als Basis nehmen, da ist die deutsche ja deutlich aktueller und umfangreicher als die englische.

Nachtrag: Diese Referenz kann dann auch sehr gut Nicht-Programmierenden Doku-Schreibern (im Sinne von Wie-mache-ich-was) als Input dienen.

So wars gedacht ;-)