Lazarus Dokumentation

[Euklid]

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.

Also die F1-Hilfe finde ich eigentlich schon ziemlich gut. Was ich meine ist eher ein Katalog mit den Lösungsansätzen zu häufig vorkommenden Standardproblemen. Und ich finde das aktuelle Wiki beinhaltet diesbezüglich bereits sehr gute Ansätze und Artikel, die einen auf dem jeweiligen Gebiet wirklich weiter bringen. Eine Integration in die F1-Hilfe halte ich nicht für notwendig, da bei einem zu großen Detailgrad der Artikel gerade die Übersichtlichkeit verloren geht, die im Fall von F1 angebracht ist.

Vielmehr sehe ich zwei Bereiche, an denen gearbeitet werden müsste:

1.: Eine vernünftige Gliederung.
Marcov hat es bereits erwähnt, die Artikel im Wiki wirken wie ein Flickenteppich. Wir brauchen eine zentrale Seite, auf denen die Standardprobleme aufgelistet sind, mit Links zu den entsprechenden Artikeln.
Auf dieser Übersichtsseite sollten die Probleme nach Rubriken geordnet sein, damit man schnell zum Ziel gelangt.

Vom zeitlichen Aufwand dürfte so eine Seite schnell einzurichten sein.

2.: Eine größere Artikeltiefe und -breite
Viele Artikel sind finde ich schon ausgesprochen gut. Aktuell werden noch nicht alle Standardprobleme im ausreichenden Umfang abgedeckt. Oft müssen wir auf Delphi-Tutorials verweisen. Der Arbeitsaufwand hier ist größer, aber schaffbar; die Grundlagen sind bereits gelegt.

- Euklid

[Socke]

1.: Eine vernünftige Gliederung.
Marcov hat es bereits erwähnt, die Artikel im Wiki wirken wie ein Flickenteppich. Wir brauchen eine zentrale Seite, auf denen die Standardprobleme aufgelistet sind, mit Links zu den entsprechenden Artikeln.
Auf dieser Übersichtsseite sollten die Probleme nach Rubriken geordnet sein, damit man schnell zum Ziel gelangt.

Eine Übersichtsseite gibt es bereits: http://wiki.freepascal.org/Lazarus_Documentation
Dort werden jedoch Dokumentation der Funktionen und der IDE, Tutorials und so weiter komplett vermischt.

[mschnell]

Also die F1-Hilfe finde ich eigentlich schon ziemlich gut....

...Dort werden jedoch Dokumentation der Funktionen und der IDE, Tutorials und so weiter komplett vermischt....

IMHO ist es extrem wichtig, dass es ein einziges Hilfe-System gibt und nicht mehrere Parallele halbfertige Ansätze. Alles andere istfür das Team nicht zu pflegen und für den Benutzer nicht sinnvoll verwendbar.

Deshalb finde ich, dass ein Wiki, dessen Seiten auch online und offline Kontext-sensitiv über F1 in der IDE aufgerufen werden können als einzige sinnvolle (und moderne) Infrastruktur dafür.

-Michael

[Michl]

IMHO ist es extrem wichtig, dass es ein einziges Hilfe-System gibt und nicht mehrere Parallele halbfertige Ansätze.

Das würde ich unterschreiben.

Deshalb finde ich, dass ein Wiki, dessen Seiten auch online und offline Kontext-sensitiv über F1 in der IDE aufgerufen werden können als einzige sinnvolle (und moderne) Infrastruktur dafür.

Eine Hilfeseite mittels Wiki erstellen zu wollen, finde ich etwas problematisch, da es für viele Autoren im Wiki leichter erscheint eine neue Struktur selber zu schaffen, als die bestehende zu aktualisieren. Ich weiss nicht, ob und wie man dieser Destrukturierungsgefahr per Wikiprinzip entgegnen kann. Leider hat das Wiki mit Reinier Olislagers auch einen der engagiertesten Autoren bzw Maintainer verloren, sodaß die Abweichungen z.B. vom deutschen zum englischen Wiki eher noch zunehmen werden.

[Socke]

Eine Hilfeseite mittels Wiki erstellen zu wollen, finde ich etwas problematisch, da es für viele Autoren im Wiki leichter erscheint eine neue Struktur selber zu schaffen, als die bestehende zu aktualisieren. Ich weiss nicht, ob und wie man dieser Destrukturierungsgefahr per Wikiprinzip entgegnen kann.

Bürokratie. Bei der bisherigen Dokumentation hast du einen Maintainer, der Änderungen zustimmt oder diese ablehnt. Er definiert auch die Struktur. Gerade Wikis haben die Schwierigkeit, eine Struktur zu etablieren, da hier ausreichend Autoren mitmachen müssen. Es müssen praktisch alle zustimmen, die neue Struktur zu verwenden. Dazu müssen die Autoren die Struktur natürlich kennen und Themen einsortieren. Zum Glück kann so etwas auch von anderen Autoren nachgeholt werden.

Leider hat das Wiki mit Reinier Olislagers auch einen der engagiertesten Autoren bzw Maintainer verloren, sodaß die Abweichungen z.B. vom deutschen zum englischen Wiki eher noch zunehmen werden.

Wenn es nur um das Übersetzen geht Ich denke, Inhalte zu übersetzen und zwischen den Sprachen synchron zu halten ist ein Ding der Unmöglichkeit. Aber man muss hohe Ziele haben um überhaupt etwas zu erreichen!

[Michl]

Gerade Wikis haben die Schwierigkeit, eine Struktur zu etablieren, da hier ausreichend Autoren mitmachen müssen. Es müssen praktisch alle zustimmen, die neue Struktur zu verwenden. Dazu müssen die Autoren die Struktur natürlich kennen und Themen einsortieren.

Genau das meine ich. Es häufen sich Kategorien wie "CodeSnippes" etc., die mMn keinen Mehrwert für das Wiki bedeuten.

Nur zum Verständnis, ich bin sehr für eine an das Wiki angelehnte Hilfe, ich könnte mir sogar vorstellen, diese in der IDE ohne Browser editierbar zu machen, mir ist z.Zt. jedoch die Umsetzbarkeit nicht ganz klar.

[marcov]

Also die F1-Hilfe finde ich eigentlich schon ziemlich gut....

...Dort werden jedoch Dokumentation der Funktionen und der IDE, Tutorials und so weiter komplett vermischt....

IMHO ist es extrem wichtig, dass es ein einziges Hilfe-System gibt und nicht mehrere Parallele halbfertige Ansätze. Alles andere istfür das Team nicht zu pflegen und für den Benutzer nicht sinnvoll verwendbar.

Genau. Man braucht nur die IDE Dokumentationen aus der wiki nach HTML zu exportieren, und ich habe schon vor Jahre gesagt das ich die dann zu fpdoc/CHM compilieren werde und man hat schon ein uniformiertes Hilfe System (vor der Ansicht der Anwender).

Aber schon DAS ist anscheinend Unmöglich weil die mediawiki Technik nicht im Griff ist.

Deshalb finde ich, dass ein Wiki, dessen Seiten auch online und offline Kontext-sensitiv über F1 in der IDE aufgerufen werden können als einzige sinnvolle (und moderne) Infrastruktur dafür.

Das ist nicht Modern, das sind alte Jahre siebziger Ideen. Mann muss nur nach die Welt gucken um an zu sehen was davon übrig ist. Das funktioniert nur in einer Akademischer Umgebung, nicht in die wirklichen Welt.

WIKI ist nur eine Idee, keine Lösung. (eben wenn sie von einer Philosophischer Ansicht besser wahre (und ich bestreite das auf Grund Eheren Erfahrungen), die Technik ist gar nicht dar. Nicht eben in erster Linie, alles ist Handarbeit)


P.s. die Leute die Wiki sagen sollen Spezifizieren ob sie es Wiki mit oder ohne Access-control vorstehen. Und wenn ohne, wie sie das in der Hand halten wollen.

[mschnell]

Das funktioniert nur in einer Akademischer Umgebung, nicht in die wirklichen Welt.

Richtig.

Ich finde eine ordentliche Software-Doku ist eine total akademische Aufgabe.

-Michael

[Socke]

Das funktioniert nur in einer Akademischer Umgebung, nicht in die wirklichen Welt.

Richtig.

Ich finde eine ordentliche Software-Doku ist einen total akademische Aufgabe.

Nein, aber die Frage, wie diese umgesetzt wird.

Genau. Man braucht nur die IDE Dokumentationen aus der wiki nach HTML zu exportieren, und ich habe schon vor Jahre gesagt das ich die dann zu fpdoc/CHM compilieren werde und man hat schon ein uniformiertes Hilfe System (vor der Ansicht der Anwender).

Aber schon DAS ist anscheinend Unmöglich weil die mediawiki Technik nicht im Griff ist.

Zurzeit fahren wir mit einem 10 Jahre alten Auto ohne TÜV. Das heißt: ein Update wäre dringend angeraten.

Die Wiki-Seiten herunterzuladen ist recht einfach möglich. Problematisch sind die Fragen: Welche Seiten werden benötigt (lässt sich zum Beispiel durch eine Kategorie lösen)? Wie werden die Inhalte untereinander verlinkt?

Welche Probleme gibt es sonst noch?

P.s. die Leute die Wiki sagen sollen Spezifizieren ob sie es Wiki mit oder ohne Access-control vorstehen. Und wenn ohne, wie sie das in der Hand halten wollen.

Bei einer Lösung mit Namespaces (wie oben von mir vorgschlagen) kann man die Berechtigungen zum Bearbeiten auf Benutzergruppen beschränken. Dann wäre eine einfache, pragmatische Lösung notwendig um in diese Gruppe zu kommen.

[creed steiger]

Es kommt noch das Problem der Aktualisierung der Inhalte bei Versionsänderungen hinzu.
Was für 2.x gilt muß nicht für 2.y gelten.
Das ist staubtrockene Arbeit.

[marcov]

Zurzeit fahren wir mit einem 10 Jahre alten Auto ohne TÜV. Das heißt: ein Update wäre dringend angeraten.

Ja. Mehr eben, der IDE Hilfe war von anfang (1998?) in der Wiki, also 15 Jahre. Dringend Zeit für etwas besseres.

Die Wiki-Seiten herunterzuladen ist recht einfach möglich.

Hast du das versucht? In sofern ich weiß behindert anti-spam Software das.

Problematisch sind die Fragen: Welche Seiten werden benötigt (lässt sich zum Beispiel durch eine Kategorie lösen)? Wie werden die Inhalte untereinander verlinkt?

Gar kein Problem. Ich mein das nicht synchron zu halten, aber nur einmal nach fpdoc oder latex format zu kovertieren.

Welche Probleme gibt es sonst noch?

Versionen (Lazarus Doku sind Versioniert in SVN, aber FPC Doku war Versioniert mit SVN, aber ist es nicht mehr. Das heißt es werden mit eine neue Generation keine Tags/branches per Versionen mehr gemacht)

fpdoc hat ein Namespace System, Latex functioniert mehr als Word Outlines. Aber man kann einfach mit SVN diffen usw

Außer das und die IDE Hilfe, nur Arbeit. Und vielleicht Übersetzung.

P.s. die Leute die Wiki sagen sollen Spezifizieren ob sie es Wiki mit oder ohne Access-control vorstehen. Und wenn ohne, wie sie das in der Hand halten wollen.

Bei einer Lösung mit Namespaces (wie oben von mir vorgschlagen) kann man die Berechtigungen zum Bearbeiten auf Benutzergruppen beschränken. Dann wäre eine einfache, pragmatische Lösung notwendig um in diese Gruppe zu kommen.

Also dann denke ich nicht das wiki wirklich so viel bringt. Access control is auch möglich mit SVN.

[mschnell]

Hmmm.

- gleich aussehende und bedienbare (z. B. Brower-basierte) Anzeige mit "F1" und einfach online zum Stöbern
- "F1" online und offline (download)
- komfortabel durchsuchbar d.h. die Datenbank für die Suche muss automatisiert erstellt werden.
- Editieren per Browser mit direkter Kontroll-Möglichkeit der endgültig formatierten "Seiten" ist (IMHO) unumgänglich, um freiwillige Schreiber nicht abzuschrecken.
- Versionskontrolle mit svn ist umumgänglich um die Synchronität mit der Software (Lazarus, lcl und fpc) zu gewährleisten
- gute Unterstützung für einen redaktionell betreuter "Freigabeprozess" für "official releases" um das Team möglichst zu entlasten
- sinnvolle und zwingend vorgegebene Strukturierbarkeit
- Import der verschiedenen existierenden Ansätze
- Import von Fremdformaten für 3rd-Party Libraries und z.B. Windows API Hilfe von Microsoft
-...

Da ist ganz schön komplexe speziell für diesen Zweck erstellte Software notwendig. (z.B. ein Fork der Wiki-Software. Ist ja vermutlich open source. PHP ? Wer hat da Lust zu ? )

Und dann ein Redaktions-Team, das die eingehenden Beiträge betreut...

Aber ohne professionelle Hilfe/Doku ist der "Akzeptanz-Rückstand" z.B. gegenüber Java nicht aufzuholen.

Wenn z.B. ein Informatik-Lehrer eine Sprache für seinen geplanten Kurs sucht mit Hilfe derer er den Schülern die Grundbegriffe des Programmierens nahe bringen will, sagt er sich:

Pascal ist die bester Programmier-Sprache zum Lernen. Die modernen Object-Pascal-Systeme Delphi und Lazarus lassen sich außerdem hervorragend für viele Zwecke praktisch einsetzen. Ideal für Desktop aber auch prima für anderes. Sie Systeme sind benutzerfreundlich und zeigen keine großen Qualitäts-Mängel. Aber Delphi ist zu teuer. Das können sich die Schüler nicht anschaffen (das freie "Turbo-Delphi" gibt es nicht mehr, so dass man es nicht mehr legal verwenden kann). Lazarus hat keine ausgereiftes Hilfe und Doku-System. Da werden die Schüler den Unterricht mit vielen Fragen aufhalten, die sie sich z.B. in "Visual Studio Express" leicht selbst beantworten können. Also muss ich wohl C++, C# oder Basic nehmen .

-Michael

[Christian]

Ich denke es sollten vor allem 2-3 Entwickler vom harten Kern dabei sein. Martin, Mathias liest hier jemand von euch mit ?

Ich wär auch dafür die unterschiedlichen Ansätze zu vereinheitlichen.
Gut fände ich z.b. eine Verzeichnisstruktur in der z.b. WikiText abgelegt wird das ganze kann man einfach aus dem Wiki konvertieren/runterladen und aktuell halten und über gut oder svn verwalten. Weiterhin lässt sich daraus z.b. einfach html zur Anzeige in ipro order browser erzeugen und gut parsen ums in der ide zu verwenden.

[Mathias]

Martin, Mathias liest hier jemand von euch mit ?

So oberflächlich lese ich noch mit, ich sehe nur, das der Thread nichts mehr mit Java zu tun hat.

Vieleicht müsste ein Mod den Thread splitten.

[Christian]

Meinte Mathias G. oder bist du in die Schweiz umgezogen ?