Vorschlag für Verbesserungen der Dokumentation

[arnoz]

Hallo zusammen,

ich habe mich jetzt durch den thread gearbeitet und parallel auf github geschaut.

Vielen Dank für die Arbeit und das Engagement. ich finde das ist ein Quantensprung in der Dokumentation.

Ich glaube die ersten grundsätzlichen Dinge habe ich verstanden. Bei nächster Gelegenheit werde ich mich genauer mit github beschäftigen und hoffe auch etwas zur Dokumentation beitragen zu können.

Arno

[Hups]

Hallo Chris!
Danke! Ich schau mir das bis zum Wochenende in Ruhe an und geb Laien-Feedback, ok? =)

SG!

[Chris M.]

Der (Stand heute) richtige Link um die (neue) Doku zu lesen ist: http://test.cometvisu.org/CometVisu/...ual/index.html

Später, wenn das ganze die entsprechende Reife erreicht hat, kommt das "test" in der URL weg.

[Hups]

Ich stehe als dümmster anzunehmender User bereit zum Testlesen und Anwendenprobieren.
Cometvisu ist ein Thema, das seit Monaten auf meiner Liste steht.
Ist das der richtige Link?

https://github.com/CometVisu/CometVi...nfig/index.rst

[Chris M.]

Chris scheint ja auch einen gewissen Wert auf die Formulierung legen.

Ja, wobei ich davon ausgehe, dass das in einem vernünftigen Rahmen ist

Da das alles in der Doku ankommt, sollte es entsprechend formuliert sein, wie man es in einer Doku erwartet. Dazu gehört eine gewisse Seriösität, bzw. man sollte eine gewisse Flapsigkeit vermeiden. Staub trocken und juristisch muss es aber auch nicht geschrieben sein.

Da die Attribut-Beschreibung auch im Editor angezeigt werden, sollte die Länge des Textes dort eine Zeile nicht überschreiten (was auch immer das an Zeichen oder Anzahl der Sätze bedeutet).

=> Das sind (bewusst!) alles keine starre Regeln, sondern bitte dem jeweils konkreten Fall anzupassen.

[peuter]

Ich nehme an, die Elemente "elements" in der XML dürfen nicht mit Erklärungen versehen werden - ebenso wie die Widgets selbst? Diese Info kommt dann woanders her.

Die Elemente und die Widgets brauchen ja schon etwas mehr Erklärung als ein/zwei Sätze, daher werden die extra in der Dokumentation beschrieben. Jedes Widget wird sowieso eine eigene Seite bekommen und die wichtigen Elemente sicher auch (Layout auf jeden Fall, Adressen reicht vielleicht ein Abschnitt irgendwo auf einer Seite, ...).

Bei den Attributbeschreibungen bin ich für kurz und knackig, wobei ich beide Beispiele von Dir als kurz und knackig beschreiben würde. Sollten halt nicht mehr als 2-3 Sätze sein und das wesentliche einigermaßen auf den Punkt bringen.

[SirTobiIV]

und noch eine:
Im Wiki sind ja durchaus einige Widgetbeschriebungen und Attributbeschreibungen vorhanden, die sich nicht in der visu-config.xsd finden.
Soll ich diese direkt übernehmen? Chris scheint ja auch einen gewissen Wert auf die Formulierung legen.

Ist so etwas in Ordnung?

Hier wird die Beschriftung für die obere linke Schaltfläche eingetragen.

oder soll ich in dem angefangenen Stil weitermachen - in etwa so?

Defines the label for the top left button.

kurz und knackig ohne weitere Erläuterungen.

[SirTobiIV]

Hi

ich habe noch eine Frage bzgl. Dokumentation der Widget Attribute in der visu-config.xsd.
Ich nehme an, die Elemente "elements" in der XML dürfen nicht mit Erklärungen versehen werden - ebenso wie die Widgets selbst? Diese Info kommt dann woanders her.

[Wurschtel]

Jetzt habe ich das Ding fast nicht mehr gefunden ..... mit dieser Formatierei muß ich mich noch intensivst beschäftigen.

[Wurschtel]

Okayyyyyyyyyyyyy ...... 80 Zeichen und dann ein "enter"

[Chris M.]

Ich hätte da jetzt wohl mal ein Worte in die index.rst getippt ..... nun muß ich pullen?

Scheint funktioniert zu haben

Könntest Du bitte noch die Zeilen so umbrechen, dass die normalerweise nicht breiter als 80 Zeichen sind (vgl. https://github.com/CometVisu/CometVi...i/Coding-style )?

Bei Code kann es manchmal schwierig sein, bei Fließtext sollte es aber meist problemlos gehen.

[Wurschtel]

Ich hätte da jetzt wohl mal ein Worte in die index.rst getippt ..... nun muß ich pullen?

[Chris M.]

Ja. Allerdings habe ich das ganze online editiert, was recht umständlich ist, da weder die Suche funktioniert, noch gibt es farbige Hervorhebungen oder gar eine Syntaxkorrektur.

Aber auch online kannst Du diese Änderung noch nachträglich deinem Branch hinzufügen, so dass das automatisch in den Pull Request angehängt wird.

Bei mir funktioniert übrigens beim online Editieren sowohl das Syntax-Highlighting als auch die Suche im Code (Cursor im Text und dann Strg+F): editor.jpg

Eine Syntaax-Korrektur gibt es auch nur bei spezialisierten Editoren. Verwende ich daher nicht, geht auch wunderbar ohne

Editieren mit eclipse klappt noch nicht. Direkte Verbindung mit Github will nicht und wenn ich das Projekt offline öffne, dann legte eclipse weitere projektdateien an, die dann im Git auftauchen.

Eclipse ist sicher ein super Programm, es kann sehr viel und wenn Programmieren das Tagesgeschäft ist's wohl oft auch passend.
Mir persönlich ist es viel zu groß und aufgeblasen, das so viel kann, dass bei mir immer alles nicht richtig funktioniert. Und trotz schnellem Rechner ist's mir zu lahm.

Ich verwende einfach einen besseren Text-Editor mit Syntax Highlighting für alle CometVisu betreffenden Entwicklungen. (Um genau zu sein: Kate und gelegentlich vim).

Oh weh, oh weh ... das wird nun richtig kompliziert!

Gerade für Nur-Gelegentlich-was-Änderer wäre meine Empfehlung daher eben nicht eine aufgeblasene Entwicklungsumgebung zu nehmen (wie Eclipse, aber auch einige andere), sondern etwas schlankes.

Gerade beim Handbuch schätze ich, dass der Online-Editor reicht. Da braucht man dann lokal gar nichts installieren und kann alles im Web-Browser mit hübscher Oberfläche lösen.

Wenn man dann doch etwas mehr möchte dann installiert man sich git (aufgrund der Einfachheit würde ich sogar zur Kommandozeilen-Version tendieren, man muss bei dem was beim Handbuchschreiben passiert gerade mal 4 Kommandos können; aber auch ein grafischer Git Client passt). Und einen leichtgewichtigen Editor.
Ich hab ihn mangels Windows nie genutzt, könnte mir aber vorstellen, dass dort Notepad++ eine gute Wahl wäre.

Ich hatte mir mal ein Lesezeichen auf "http://peuter.github.io/CometVisu/de/manual/" gelegt, [...].

Also der aktuelle Stand ist nun unter http://test.cometvisu.org/CometVisu/...ual/index.html zu finden. .

Da wir gerade beim Handbuch und der Webseite Vollgas geben, ist der Link schon etwas offizieller geworden. Der finale Schritt wird dann sein, dass das Handbuch direkt unter http://www.cometvisu.org/ zu finden sein wird.

[peuter]

Das heißt, das man tunlichst nur in https://raw.githubusercontent.com/Co...nfig/index.rst bearbeiten soll.
Das ist auch irgendwo in github und wird auch gegengelesen?

Die von mir verlinkten Dateien sind an der Stelle nur lesbar, wenn Du da Änderungen machen möchtest, erstellst Du die eine lokale Kopie, änderst dort und stellt dann einen sogenannten Pull-Request. Dieser wird dann gegen gelesen und entweder so übernommen oder Verbesserungsvorschläge gemacht.

Die allgemeine Vorgehensweise ist mittlerweile auch in der Dokumentation beschrieben: http://test.cometvisu.org/CometVisu/...lab/index.html

Wie erfolgt dann die Formatierung? Das ist ja auch wieder so eine Art Geheimsprache.

Ist nicht geheim, hab ich in diesem Thread auch schon gesagt. Nennt sich reStructuredText oder kurz RST:
https://de.wikipedia.org/wiki/ReStructuredText

Kurzreferenz:
http://thomas-cokelaer.info/tutorial...st_syntax.html

Die Beschreibung dazu, mir der für unsere Doku relevanten Syntax fehlt noch in der CV-Doku, muss ich noch schreiben.

[Wurschtel]

Das heißt, das man tunlichst nur in https://raw.githubusercontent.com/Co...nfig/index.rst bearbeiten soll.
Das ist auch irgendwo in github und wird auch gegengelesen?

Wie erfolgt dann die Formatierung? Das ist ja auch wieder so eine Art Geheimsprache.

Noch die Antwort auf deine Frage: Ja! Da fehlen noch ein paar Worte zur Klarstellung.