Lazarus Dokumentation

[pluto]

Eben: vieles geht, das meiste auch einfach, aber man findet es nicht.

Das liegt wiederum daran, dass Lazarus im Gegensatz zu Java von Freiwilligen Entwicklern Entwickelt wird.

Und wer hat schon Lust eine Doku zu schreiben? Ich habe mir das einigemale vor genommen, habe es dann aber sein gelassen.
Vorstellbar wäre höchsten eine Art Artikel Serie, zu einzelnen Thmen. Z.B. heute nehmen wir uns TFileStream vor, und morgen nehmen wir uns TBitMap vor.

[Socke]

Und wer hat schon Lust eine Doku zu schreiben? Ich habe mir das einigemale vor genommen, habe es dann aber sein gelassen.
Vorstellbar wäre höchsten eine Art Artikel Serie, zu einzelnen Thmen. Z.B. heute nehmen wir uns TFileStream vor, und morgen nehmen wir uns TBitMap vor.

Ich sehe das so: je mehr Dokumentation ich schreibe, desto eher kann jemand anderes an meinem Code weiterarbeiten und ich muss weniger Code schreiben.

Auf der anderen Seite sprichst du Tutorials an. Da finde ich es schade, dass immer wieder auf Delphi-Tutorials hingewiesen wird/werden muss.

[pluto]

Ich sehe das so: je mehr Dokumentation ich schreibe, desto eher kann jemand anderes an meinem Code weiterarbeiten und ich muss weniger Code schreiben.

Stimmt, aber ich kann mich einfach nicht überwinden eine Doku zu schreiben. Auch wenn es hilfreich wäre. Auch für mich selbst.

Auf der anderen Seite sprichst du Tutorials an. Da finde ich es schade, dass immer wieder auf Delphi-Tutorials hingewiesen wird/werden muss.

Ja, dass ist finde ich der größte Nachteil. Es gibt zwar ein Lazarus Wiki, aber trotzdem muss man in der Regel auf Delphi Tutorials verweisen.

Im Internet nach Lösungen suchen gehört doch heute zum Handwerk. Auch bei der Arbeit mit Javascript, HTML/CSS, PHP etc. ist man doch dauernd online am irgendwelche Libraries und Snippets zussammenkramen, bevor man das Rad neu erfindet.

Ja, aber es gibt Leute, die mögen einfach nicht Suchen. Ich suche Ständig nach Irgendwelche Informationen. Auch in Zusammenhang mit Arduino. Man muss halt Lernen, wie man am besten Infos finden kann.

Halbwegs verstehen sollte man den so "geklauten" Code natürlich schon.

Naja, wenn du danach gefragt wirst. Es reicht eigentlich aus, wenn du weißt was er macht *G* und wie man ihn Anwendet.

[mschnell]

Im Internet nach Lösungen suchen gehört doch heute zum Handwerk.

Klar. für "ungewöhnliche" Aufgaben ist das oft hilfreich und notwendig. Aber wenn man x verschiedene Ansätze unterschiedlicher Qualität findet und die dann ausprobieren muss, hat man es oft schneller (und besser), in jedem Fall aber für sich selbst verständlicher selber programmiert, (Und dann veröffentlicht man es im Internet und verschärft das Problem.) Deshalb war der Wunsch explizit, dass in der Lazarus Doku nicht irgendwelche, sondern verifizierte Lösungen für Standard-Probleme vorgeschlagen werden.

Auch bei der Arbeit mit Javascript, HTML/CSS, PHP etc. ist man doch dauernd online am irgendwelche Libraries und Snippets zussammenkramen, bevor man das Rad neu erfindet.

Klar. Der Poster hatte nur angemerkt, dass in Lazarus relativ zu anderen Systemen nur relativ wenig "out of the box" verfügbar sei, und dass das die Akzeptanz von Lazarus schmälert.

Es reicht eigentlich aus, wenn du weißt was er macht.

Genau das ist das Problem (meist: Doku = "look at the source"). Mangels Doku weißt Du meist nicht genau was er macht. Da Google die Source nicht versteht, ist das, was es vielleicht wirklich in guter Qualität gibt, nicht zu finden. Es gibt natürlich keine Qualitäts-Garantie, und Software ordentlich zu testen ist mindestens so viel Arbeit wie sie zu schreiben.

-Michael

[marcov]

Man bräuchte halt jemanden, der sich dessen annimmt.

Ich habe auch schon versucht, mich bei der Erweiterung der (englischen) Doku für Lazarus zu beteiligen. Leider sind die Tools, die für das Doku-System benutzt werden müssen nicht wirklich brauchbar und alle schreien nach Veränderung aber verständlicher Weise hat keiner Lust und Zeit. Es existieren verschiedene inkompatible Ansätze.

Wir haben vor ca. 2 Jahren darüber in der englischen Mailing-Liste genügend diskutiert. Ergebnis: man müsste das System auf Wiki-Basis aufbauen, damit Freiwillige eine Chance haben, mitzumachen.

Ein paar Leute haben so etwas gesagt. Aber alle Leute die tatsächlich etwas mit Dokumentation machen haben das als Quatsch bezeichnet. Man gibt immer die Methoden oder Werkzeugen den Schuld, nie die Leute. Es hat mehrere Versuchen mit wiki's gegeben, und die haben nicht wirklich mehr nützliche Dokumentation generiert. (aber ein ganze menge Zeit gegessen es zu starten)

Man braucht sich nur den heutigen Wiki an zu sehen, das ist alles eine fragmentierten menge Artikel ist, oft ohne deutlicher Anfang oder Ende.

Und man will tatsächlich Dokumentation die mehrere Größen an Umfang haben in einer Wiki werfen? Das ist hoffnungslos!

Damit das Sinn macht, muss die Software für die "F1" - Hilfe in Lazarus so angepasst werden, dass sie auf die Datenbank mit dem Wiki-Text zugreift und außerdem muss ein Konverter geschrieben werden um den vorhandene Hilfetext komplett in Wiki-Form zu überführen.

Den IDE Hilfe von Lazarus ist wiki basiert, und immer ein Mist da etwas zu finden weil es meistens nicht per Version ist. Es ist immer ein Mischung von Produktions und Trunk Versionen. Die heutige XML Dokumenten sind in Subversion eingetragen, und damit automatisch Versioniert.

- Windows API

Kaum zu machen.

- Linux API

Das wird schwierig. Die einfache libc functionen sinds meistens schon in Baseunix, der Rest benötigt etwas mehr als nur C->Pascal übersetzen. (zb KDE oder DBUS etc sind nicht einfach mengen Prozedur Calls wie die Windows API)

- MAC API

Fast alle neue Schnittellen sind in Objective C, auch meistens hoffnungslos.

Man kann sich besser die Zeit sparen solche APIs zu übersetzen und etwas wie das Lazarus Buch schreiben (eine Bunde Artikel) , wie man auf ein bestimmtes OS etwas macht.

[mschnell]

Man braucht sich nur den heutigen Wiki an zu sehen, das ist alles eine fragmentierten menge Artikel ist, oft ohne deutlicher Anfang oder Ende.
Und man will tatsächlich Dokumentation die mehrere Größen an Umfang haben in einer Wiki werfen? Das ist hoffnungslos!

Liegt das tatsächlich daran, dass das mit der Wiki-Technik nicht möglich ist, oder daran, dass momentan die Unterstützungs-Texte auf FPDoc, Wiki (und u.U. andere Systeme) versprengt sind und deshalb es niemand in die Hand nehmen kann, die Wiki-Ansätze redaktionell zu betreuen (zumal "F1" die Wiki-Texte nicht zeigen kann).

Den IDE Hilfe von Lazarus ist wiki basiert, und immer ein Mist da etwas zu finden weil es meistens nicht per Version ist. Es ist immer ein Mischung von Produktions und Trunk Versionen. Die heutige XML Dokumenten sind in Subversion eingetragen, und damit automatisch Versioniert.

Yep. Ist das Backlog von Wiki schlechter als svn ? Wenn ja, kann man es nicht verbessern oder Wiki an svn koppeln ?

Ein weiteres Problem von Wiki-Texten könnte (wie bereits angesprochen) die Strukturierung sein. Ich weiß nicht ob die Wiki Bordwerkzeuge da ausreichen.

Windows API: Kaum zu machen.

Delphi macht das seit vielen Jahren ganz Prima. Ich weiß nicht ob die Delphi-Hilfe-Technik insgesamt gut ist, aber offensichtlich ist das einbinden der Microsoft API Hilfe gut gelungen.

-Michael

[Socke]

Den IDE Hilfe von Lazarus ist wiki basiert, und immer ein Mist da etwas zu finden weil es meistens nicht per Version ist. Es ist immer ein Mischung von Produktions und Trunk Versionen. Die heutige XML Dokumenten sind in Subversion eingetragen, und damit automatisch Versioniert.

Yep. Ist das Backlog von Wiki schlechter als svn ? Wenn ja, kann man es nicht verbessern oder Wiki an svn koppeln ?

Es ginge über eine Namenskonvention bzw. über Namespaces:

• FPC_Trunk:SysUtils.FileOpen enthält die Dokumentation der Funktion FileOpen der Unit Sysutils für den aktuellen Entwicklungszweig.
• Bei einem Release werden die Trunk-Seite nach beispielsweise FPC_2.8.0:SysUtils.FileOpen kopiert.
• Bei Release von Version 2.8.1 wird FPC_2.8.0:SysUtils.FileOpen nach FPC_2.8.1:SysUtils.FileOpen kopiert und dort angepasst. Wenn keine Änderungen vorliegen, wird einfach nur ein Link gesetzt.
• Für die offizielle Lazarus-Dokumentation wird dann bspw. der Namespace Lazarus: verwendet
• Bei den Packages dürfen wir uns noch etwas schlaues überlegen (LCL, LCLBase, etc.)

Eine direkte Kopplung and Subversion ist realistisch nicht machbar.

Ein weiteres Problem von Wiki-Texten könnte (wie bereits angesprochen) die Strukturierung sein. Ich weiß nicht ob die Wiki Bordwerkzeuge da ausreichen.

Die reichen mit Sicherheit aus: Schau dich mal in der Wikipedia um. Über Kategorien kann man eine Struktur abbilden. Über Vorlagen kann man eine Liste von Artikeln in eine Seite einbinden etc. Für Themenbereiche erstellt man Portale, die die einzelnen Themen anschneiden und den Leser weiterleiten.

[pluto]

Ich denke, da müsste was einfacheres her. Ich habe mir schon einige Male dazu Gedanken gemacht.

Man müsste ganz Leicht eine Möglichkeit haben, Sachen zu beschreiben. Z.B. Was macht TFileStream. Was macht die Funktion Pos. Ich stelle es mir eigentlich so vor:

Es gibt pro Unit eine Liste, mit den Klassen, Funktionen/Proceduren und soweiter.
Jeder der Will kann jetzt eine Sache davon beschreiben. Am besten mit Beispiel(oder auch mehren) und Hinweisen. Das das klappt zeigt ja schon FindFirst.
Bei mir klappt das jetzt zwar nicht. Aber es hat immer geklappt.

Allerdings fällt es natürlich schwer eine Struktur rein zu bekommen.

Keiner möchte erst eine Dokumentation durchlesen um eine Dokumentation zu schreiben. Das ist schon ein Widerspruch in Sich.

Das muss dann nach und nach aufgebaut werden und mit Beschreibungen gefüttert werden. Welche Sprache ist eigentlich erst mal egal. Ich kann z.b. kein Englisch. Wenn ich mir jetzt im Internet die Foren Beiträge anschaue, bin ich nicht alleine.

[marcov]

Keiner möchte erst eine Dokumentation durchlesen um eine Dokumentation zu schreiben. Das ist schon ein Widerspruch in Sich.

Die meisten ja. Das ist das große Problem. Es gibt dafür keine fundamentale Lösung. Man kann versuchen die fpdoc editors weiter zu arbeiten (die haben schon etwas ähnliches in Prinzip), und damit einfach patches zu generieren.

Aber etwas Mühe muss man sich immer geben. Anders verschiebt das Problem nur eine große menge Beitragen von niedriger Qualität zu administrieren zu etwas brauchbares.

Oft können die Redakteuren oft in weniger Zeit etwas neues machen dann die bestehende Beitragen zu etwas auf zu arbeiten.

[mschnell]

Es ginge über eine Namenskonvention bzw. über Namespaces: ...

Das Versioning müsste vermutlich irgendwie automatisiert sein. Man kann kaum von den einzelnen Hilfetext-Autoren verlangen, das ordentlich durchzuziehen. Und manuelle redaktionelle Betreuung wird sehr aufwendig.

-Michael

[mschnell]

Keiner möchte erst eine Dokumentation durchlesen um eine Dokumentation zu schreiben. Das ist schon ein Widerspruch in Sich.

Ein "Widerspruch in sich" ist das nicht, aber ein ernsthafter - für professionelle Dokumentationssysteme allerdings unvermeidlicher - Hinderungsgrund. Professionelle Dokumentation (wie bei Delphi) ist teuer (also aufwändig) und von einem Freeware-Projekt kaum zu leisten. Meiner Ansicht nach genau das (und der Wunsch nach Support) der Grund warum es immer noch "Standard"-Software gegen Geld gekauft wird. Eigentlich gibt es ja auch alles (und funktionell teilweises besser) "für umsonst".

-Michael

[Socke]

Es ginge über eine Namenskonvention bzw. über Namespaces: ...

Das Versioning müsste vermutlich irgendwie automatisiert sein. Man kann kaum von den einzelnen Hilfetext-Autoren verlangen, das ordentlich durchzuziehen. Und manuelle redaktionelle Betreuung wird sehr aufwendig.

Man kann einzelne Abschnitte/Absätze mit vordefinierten Templates markieren. Dann ist auch klar, worauf man sich bezieht; Nachteilig wirkt sich dann aber die fortlaufende Entwicklung aus. Zum Beispiel ist die Dokumentation für die FPC Versionen vor 2.0 eher von historischer Bedeutung und stört erheblich den Lesefluss.

[pluto]

Dann schreibt man eine Version hin, wo das so ist.

Das ändert sich ja nicht Ständig. Ich glaube, es ist besser, etwas zu haben statt gar nichts.
Wenn wir nur das äußere Interface beschreiben, also die Sachen, die am meisten Verwendet. Müsste das gehen.
Die Intern Sachen ändern sich ja laufend.

[theo]

Habe jetzt nicht den ganzen Thread durchgelesen, aber nur kurz ein Gedanke:

Es ist vergleichsweise einfach, für eine stabile kommerzielle Version (z.B. Delphi 7) eine Doku zu schreiben.

Aber ein System, welches dauernd in Veränderung ist, und wo z.T. auch aufgrund unterschiedlicher Entscheidungsträger Dauerprovisorien errichtet werden müssen (z.B. die ganzen Laz UTF-8 Sachen), entmutigt einen Doku Schreiber.
Ich war ja eigentlich immer interessiert an Unicode, aber ich habe mich da irgendwann "ausgeklinkt".
Ich kann nicht mehr sagen, was "Stand der Technik" bei FPC ist.

Ein anderes Beispiel ist hier: http://wiki.lazarus.freepascal.org/LazActiveX

Da nimmt sich einer die Mühe, LazActiveX zu beschreiben und mit Beispielen zu versehen, die leider schon wieder komplett veraltet sind.
Und so hängt das da rum, und man ist sich nicht ganz sicher, ob "nichts" nicht fast besser wäre.

[af0815]

Hallo,

um auch noch etwas Senf dazu zu geben.

Ich habe ein wenig Erfahrung gesammelt mit dem Hilfesystem, der SVN Version, dem LateX System im Hintergrund

Die Hilfe muss wie auch Lazarus/fpc fähig sein in verschiedenen Sprachen zu arbeiten, am besten auch offline. Die Wiki ist eine gute Basis, nur muss eine entsprechende strukturierte Basis da sein. Inhalt ist dort genügend. Weiters ist auch die Version von Lazarus bzw. fpc ein Problembereich.

Und - man sollte das in einen richtig benannten Thread diskutieren (wiedermal )