Lazarus Dokumentation

[mschnell]

Die meiste Doku wird von Leute wie Michael van Canneyt gemacht in fpdoc format.

Dafür sind wir auch sehr dankbar !

Aber der Ausgangspunkt der Diskussion war, dass vorgeschlagen wurde nicht über die Hilfe zu meckern, sondern se zu verbessern. Das ist natürlich ein guter Ansatz. Nur wenn man dafür den Umgang mit FPDOC / Latech etc lernen muss und sich das Ergebnis dessen, was man da gebastelt hat nicht anschauen kann, bevor man es dem Team zur Beurteilung vorlegt, macht das keiner.

-Michael

[af0815]

Aber der Ausgangspunkt der Diskussion war, dass vorgeschlagen wurde nicht über die Hilfe zu meckern, sondern se zu verbessern. Das ist natürlich ein guter Ansatz. Nur wenn man dafür den Umgang mit FPDOC / Latech etc lernen muss und sich das Ergebnis dessen, was man da gebastelt hat nicht anschauen kann, bevor man es dem Team zur Beurteilung vorlegt, macht das keiner.

Ich sehe das nicht so. Das mit den lernen eght recht schnell, WENN man sich dafür interessiert und es auch Dokumentation darüber gibt.

Es muss erst mal ein Team geben, das sich für den Inhalt, nicht die Technik dahinter interessiert.

Was sind die Voraussetzungen für ein arbeiten an der Hilfe:

A) Grundlegende Kenntnisse in Latex und Lynx
B) Kenntnisse über FPDoc und LazDE
C) Basiswissen über svn und git (Checkout, Update, Commit)
D) Kenntnisse über den buildprozess der Hilfe (fpmake, make, commandline)

Aktuell sieht es so aus, als würde die Erzeugung der Hilfe nicht unter Windows funktionieren, sonder nur unter Linux. Ob das ganz einfach daran liegt das keiner unter Windows kompiliert oder ein grundlegendes Problem ist, habe ich noch nicht herausgefunden. Das werde ich mir als Punkt umhängen.

Zusammenfassung:
1) Die Technik ist nicht das Problem, es ist (fast) alles vorhanden
2) Der Inhalt ist nicht das Problem, es ist alles vorhanden (auf Englisch zumindest)

Es gibt somit nur Arbeit, nur wer findet sich dafür

[mschnell]

Was sind die Voraussetzungen für ein arbeiten an der Hilfe:

A) Grundlegende Kenntnisse in Latex und Lynx
B) Kenntnisse über FPDoc und LazDE
C) Basiswissen über svn und git (Checkout, Update, Commit)
D) Kenntnisse über den buildprozess der Hilfe (fpmake, make, commandline)

Ich finde das zusammen ist eine verdammt hohe Hürde.
Wenn eine mit Delphi oder Visual Studio vergleichbare Hilfe entstehen soll, werden eine ganze Menge Hilfe-Schreiber gebraucht. Das wird so nicht klappen.

Aktuell sieht es so aus, als würde die Erzeugung der Hilfe nicht unter Windows funktionieren, sonder nur unter Linux. Ob das ganz einfach daran liegt das keiner unter Windows kompiliert oder ein grundlegendes Problem ist, habe ich noch nicht herausgefunden. Das werde ich mir als Punkt umhängen.

Zusammenfassung:
1) Die Technik ist nicht das Problem, es ist (fast) alles vorhanden
2) Der Inhalt ist nicht das Problem, es ist alles vorhanden (auf Englisch zumindest)

Die "Technik" scheint alles andere als "problemlos überall" zu funktionieren und ist schwer bedienbar und in Teilen kaum bis gar nicht dokumentiert.
Da scheint es mir durchaus überlegenswert, auf ein neues Hilfe-Generierungs-System "FPDoc2" umzusteigen, das de Punkte A...D umfasst und automatisiert (svn, Buildprozess) bzw. vermeidet (LateX) oder verbessert (Komfortables Ansehen des Ergebnisses direkt nach der Editierung). Das wird man natürlich komplett in Lazarus programmieren, das ja alle notwendigen Tools zur Verfügung steht (und Spaß macht).

Heutzutage ist meiner Ansicht nach als Viewer nur der Browser sinnvoll. Der "Output" des Hilfe-Generierungs-Prozesses müsste also HTML sein, wie die "Datenbank" aussieht muss diskutiert werden (z.B. SQLite).

Es ergeben sich da - nach einer Grundsätzlichen Strategie-Entscheidung - diverse Teilaufgaben, die Sub-Teams übernehmen würden.

-Michael

[af0815]

Die "Technik" scheint alles andere als "problemlos überall" zu funktionieren und ist schwer bedienbar und in Teilen kaum bis gar nicht dokumentiert.

Mal eine Unterscheidung, Benutzerteil (in der IDE) sollte soweit Ok sein. Der Authorenteil muss mal verstanden sein. Etwas wissen kann man aber voraussetzen.

Da scheint es mir durchaus überlegenswert, auf ein neues Hilfe-Generierungs-System "FPDoc2" umzusteigen, das de Punkte A...D umfasst und automatisiert (svn, Buildprozess) bzw. vermeidet (LateX) oder verbessert (Komfortables Ansehen des Ergebnisses direkt nach der Editierung). Das wird man natürlich komplett in Lazarus programmieren, das ja alle notwendigen Tools zur Verfügung steht (und Spaß macht).

Wieso schreit jeder sofort nach einem neuen System ? Damit wird die Hilfe nicht für Anwender besser verfügbar. Die bisherigen Tools funktionieren ja, wenn man will. Wenn auch der Erstellungsprozeß der Hilfe transparenter wird, so ist es auch leichter damit zu arbeiten. Eine Verbesserung der Tools ist nur dann sinnvoll wenn der Prozess auch klar ist (wenn nötig !).

Ein Team ja, aber nur zum Arbeiten mit dem aktuellen System.

[mschnell]

Wieso schreit jeder sofort nach einem neuen System ?

Weil mit dem aktuellen Autoren-System die Hilfe seit Jahren in Benutzer-Freundlichkeit und Ausgereiftheit weit hinter dem Stand der Software hinterherhinkt.

Der Grund ist offensichtlich, dass nur die ohnehin überlasteten Software-Autoren in der Lage sind, die Hilfe zu pflegen. Mit einem problemlos anwendbaren System könnte man die Anwender motivieren, Beiträge zu leisten.

Ich würde (und habe auch schon erfolglos versucht) für die Nischen in denen ich mich tummele (MultiThreadding, NoGUI, embedded, ...) die gerade dort vorhandenen Dokumentationslücken immer dann zu füllen, wenn ich herausbekommen habe, wie bestimmte Sachen funktionieren.

-Michael

[af0815]

Ich würde (und habe auch schon erfolglos versucht) für die Nischen in denen ich mich tummele (MultiThreadding, NoGUI, embedded, ...) die gerade dort vorhandenen Dokumentationslücken immer dann zu füllen, wenn ich herausbekommen habe, wie bestimmte Sachen funktionieren.

Probier es mal mit fpdoc und LazDE, die Lücken zu füllen, wenigstens mal eine zur Probe.

Ich bin gerade dabei mir wieder eine Buildumgebung (Debian) zu schaffen für die Dokumentation. Die habe ich schon mal am laufen gehabt, leider existiert die Maschine nicht mehr. Also ohne Schweiss kein Preis.

[marcov]

af0815: ich habe es letzter Vorjahr auf Windows versucht, und man kann sehr weit kommen mit eine default texlive latex installation. (nach PDF wenigstens, aber das ist genug für Probelesen)

Die Makefiles sind aber ein Problem, aber ein kleiner Problem als Mediawiki plugins schreiben

Für kleine Texten brauch man typisch nicht zu Kompilieren, und kann man einfach mit notepad editieren und dann als DIFF einsenden (mit nicht mehr Latex Kenntnisse als Outline und Umgang mit Spezialzeichnen).

M.Schnell: Ich bin mich gar nicht bewusst das Dokumenten in irgendwo eines Format oder mit eben grobe Fehler jemals verweigert sind. Die sind immer von Autoren verwirkt worden.

Man muss nicht vergessen das das Heutige System gar nicht optimiert ist weil keiner es versucht. (und es ist WIRKLICH nicht so schwierig).


Auch stellt man das Wiki Alternativ sich viel zu einfach vor. Auch da wird es Struktur/Regeln, Access Control usw geben. Und alles dafür muss man auch lernen

[marcov]

Wenn eine mit Delphi oder Visual Studio vergleichbare Hilfe entstehen soll, werden eine ganze Menge Hilfe-Schreiber gebraucht. Das wird so nicht klappen.

Aber mit Wiki wird das auch nicht passieren.

Die Autoren sind überhaupt nicht da, die bestehen nur in die Fantasie von Leute die das System ändern wollen. Sie nennen nie wirkliche Zahlen, und haben sich gar nicht mit Hilfe bemüht.

Sie sind noch zu faul um aus den WIki Historie wirkliche Autoren und beitrage Statistiken zu holen (die Lazarus IDE hilfe IST wiki managed), um ihre eigene Theorie das Wiki eine Autoren Steigerung verursacht zu unterschreiben.

Es ist nur reine Spekulation und Demagogie.

[Socke]

Man muss nicht vergessen das das Heutige System gar nicht optimiert ist weil keiner es versucht. (und es ist WIRKLICH nicht so schwierig).

Das FPDoc-System finde ich wunderbar passend, weil hier der Programmquelltext und die Benutzer-Dokumentation getrennt wird. Das Format ist meines Erachtens einfach erlernbar. Die Werkzeuge dahin sind jedoch ein wenig problematisch und können durchaus optimiert werden. Zum Beispiel habe ich noch kein Tool gefunden um die XML-Dateien dem aktuellen Quelltext anzupassen (neue Bezeichner aufnehmen, alte entfernen).

[m.fuchs]

Das FPDoc-System finde ich wunderbar passend, weil hier der Programmquelltext und die Benutzer-Dokumentation getrennt wird. [...]

Interessant, das empfinde ich eigentlich als Nachteil. Meiner Meinung nach, sollte die Doku immer nahe am entsprechenden Quellcode stehen. Also im Programmquellcode. Deswegen benutze ich auch PasDc anstelle von FpDoc.

[Christian]

Meine Erfahrung spiegelts genau umgedreht wieder. In der fpdoc Hilfe sind ich seltenst mal Beispiele oder eine sinnvolle Hilfe das sind meisst nur einzeiler die nicht wirklich erklären was das ist. Im Wiki gibts Anleitungen.

[mschnell]

Probier es mal mit fpdoc und LazDE, die Lücken zu füllen...

Da habe ich vor ein paar Jahren schonmal angesetzt und (trotz intensiver Hilfe von Graeme) frustriert aufgegeben.

..wenigstens mal eine zur Probe.

Guter Witz
Schon für den erstem Erfolg muss man ja den ganzen Vorgang beherrschen. Ist diese Hürde einmal überwunden ist es egal ob man einen oder 100 Texte schreibt.

Ich habe mich aber nur als Beispiel zitiert. Es werden zig Hilfetext-Schreiber benötigt, die dann aber beim ersten zaghaften Versuch sofort an der Hürde scheitern und demotiviert sind.

-Michael

[mschnell]

Auch stellt man das Wiki Alternativ sich viel zu einfach vor. Auch da wird es Struktur/Regeln, Access Control usw geben. Und alles dafür muss man auch lernen

Stelle ich mir nicht wirklich "einfach" vor. Die Wiki Technik ist (finde ich) als Editor ideal, weil man (a) das Ergebnis sofort überprüfen kann und (b) die Handhabung allgemein recht bekannt und gut dokumentiert ist, (c) Die Formatierungsmöglichkeiten ausreichend sind und (vermutlich) weniger schwierig zu Handhaben als bei LateX sind, und (d) Standard-Funktionalitäten wie z.B. "Rollback" und Autoren-Kennung sehr gut geregelt sind.

Daraus folgt natürlich (weil Wiki ja mit dem Browser angesprochen wird), dass auch die F1-Hilfe-Darstellung - die ja genau so aussehen soll, wie der Hilfe-Autor es mit Wiki designet hat - mit dem Browser dargestellt wird. Lazarus braucht also ein neues Hilfe-Viewer Plugin, das auf einer neuen "Datenbank" arbeitet und HTML-Code generiert und den Standard-Browser zur Darstellung aufruft. (Hier muss also Software geschrieben werden.)

Das muss auch offline gehen (auf Basis einer Art Datei-Basierter Datenbank [z.B. SQLite, zur Not auch XML], die man downloaden kann).

Außerdem kann man die Wiki-Editierung nicht "wild" laufen lassen, sondern muss "irgendwie" (mediaWiki Plugins ??? ) dafür sorgen, dass automatisch die Struktur (Kapitel-Struktur, Querverweise, Versionen) eingehalten wird. (Hier muss also Software geschrieben werden.)

Desweiteren muss die vorhandene "F1" Hilfe in das neue Format gebracht werden, indem alle Quellen, die FPDoc verarbeitet, einbezogen werden. "Automtische" Text aus Quell-Dateien (kommen da die ganzen "Einzeiler" in der F1 Hilfe her ?) müssen natürlich auch automatisch bei Milestones einbezogen werden. (Hier muss also Software geschrieben werden.)

Das ganze ist also eher unter dem Begriff "FPDoc2" als unter dem Namen "Wiki-Hilfe" zu sehen.

-Michael

[mschnell]

Die Autoren sind überhaupt nicht da, die bestehen nur in die Fantasie von Leute die das System ändern wollen.

Ich kann natürlich nur von mir auf andere schließen.
Ich schreibe sehr gerne solche Texte. Wenn mir aber "jemand oder etwas, das ich unterstützen will" Steine in den Weg legt, gebe ich (zu) schnell frustriert auf.

-Michael

[Socke]

Auch stellt man das Wiki Alternativ sich viel zu einfach vor. Auch da wird es Struktur/Regeln, Access Control usw geben. Und alles dafür muss man auch lernen

Stelle ich mir nicht wirklich "einfach" vor. Die Wiki Technik ist (finde ich) als Editor ideal, weil man (a) das Ergebnis sofort überprüfen kann und (b) die Handhabung allgemein recht bekannt und gut dokumentiert ist, (c) Die Formatierungsmöglichkeiten ausreichend sind und (vermutlich) weniger schwierig zu Handhaben als bei LateX sind, und (d) Standard-Funktionalitäten wie z.B. "Rollback" und Autoren-Kennung sehr gut geregelt sind.

a) Bei einem funktionsfähigem Build-System ist das auch mit LaTeX möglich. Dazu müsste es natürlich soweit dokumentiert sein, dass jeder sich sein System in ca. 30 Minuten einrichten kann.
c) Die Möglichkeiten sind ausreichend; willst du eine Einheitliche Struktur, wirst du nicht umhin kommen, Mediawiki Templates zu erstellen und in von anderen Leuten erstellten Seiten einzupflegen. Die Handhabung beider Auszeichnungen ist meines Erachtens nicht schwieriger oder leichter. Solange ich mich auf die wenigen Standardformatierungen beschränke attestiere ich LaTeX eine bessere Lesbarkeit. Bei komplexen Formatierungen steigt die Lernkurve in LaTex sehr schnell.
d) Gibt es bisher auch schon per Subversion.

Außerdem kann man die Wiki-Editierung nicht "wild" laufen lassen, sondern muss "irgendwie" (mediaWiki Plugins ??? ) dafür sorgen, dass automatisch die Struktur (Kapitel-Struktur, Querverweise, Versionen) eingehalten wird. (Hier muss also Software geschrieben werden.)

Diese "Software" wird es meiner Sicht nach nicht geben. Bitte definiere doch einmal:

• Welche Artikel sind betroffen? Wie werden diese von anderen Artikeln im Wiki abgegrenzt?
• Wie wird diese Struktur umgesetzt? Warum lässt sich diese nicht mit den bisherigen Wiki-Möglichkeiten umsetzen?
• Welche Querverweise können automatisch erzeugt werden? Welche dürfen nicht automatisch erzeugt werden? Welche Gemeinsamkeiten gibt es?
• Wie sollen die betroffenen Lazarus-/FPC-Versionen für den Leser kenntlich gemacht werden? Wie soll dies im Wiki-Text oder in der Artikelstruktur hinterlegt werden?