Diskussionen und Krempel (alt: Verbesserungen Doku v4)

[AND51]

So, da wär ich mal wieder... Ich hoffe, es geht jetzt!

> Vielleicht sollte man ein neues Handbuch im PDF-Format schreiben
Und wer ist 'man'?

> aber die F1-Help kann und soll nur Referenz sein
Gut, wenn das so bleiben soll, wäre es wirklich gut,, eine Art Handbuch zu haben in der das detailliert(er) drin steht!

> @AND , setz dich hin und... [bla]
Ich sag lieber nicht, was ich davon halte. Nur so viel: Das mache ich aus verschiednen Gründen nicht.

> und wenn du damit fertig wirst, bekommt du dafür hohes ansehen von uns allen
Das ist korrekt.

> und wenn das ding wirklich gut ist, kommts vielleicht auch ins gesamtpaket
Sehr schöner Satz, wirklich! Nur das "vielleicht" macht wieder alles zunichte. Eigentor!
Ich könnte hieran noch anknüpfen, aber ich schrieb ja bereits, dass ich mich zu den Gründen nicht äußern möchte.

Dass aber jemand (vielleicht der Hersteller? ) eine Art Handbuch verfasst, ist aber wirklich keine schlechte Idee. Diese würde ich auch begrüßen.

[Kaeru Gaman]

das problem ist, das "der Hersteller" ein absoultes mini-team ist. das weißt du doch.

und gerade die super-foren, die es für PB gibt, mit so vielen leuten die selbständig mitarbeiten,
geben ihnen die freiheit, sich hauptsächlich mit proggen zu beschäftigen und was gutes auf die beine zu stellen,
und nicht mit übermäßig doku aufgehalten zu werden.

ich selber bevorzuge gute doku, ich fordere sie gerne mal ein,
wenn ich ein wirklich beschissen dokumentiertes projekt unter die finger bekomme.

aber wenn sich Fred & Freak & Co nach dem spruch meines professors richten würden
"50% der Arbeitszeit sollte in die Dokumentation fließen, und nur 50% in das eigentliche Programmieren"
dann wären wir heut noch nich bei 3.5


> Nur das "vielleicht" macht wieder alles zunichte.
ich kann nicht für Fred und Freak sprechen.
dazu käme bestimmt noch, dass man dann auch mannigfaltig übersetzer bräuchte....

[AND51]

> das problem ist, das "der Hersteller" ein absoultes mini-team ist. das weißt du doch.
Das ist richtig. Es soll wirklich nicht schäbig rüberkommen, aber warum soll ich mir den Allerwertesten aufreißen und sehe keinen Cent dafür? Das ist bestimmt nicht wenig Arbeit. Dazu kommt noch die laufende Arbeit: Schließlich wollen künftige PB Versionen auch ein aktuelles Handbuch haben. Ich bevorzuge, wenn ein Projekt nicht OpenSource wird, sondern in den Händen von einem (oder ein sehr kleinem Team) bleibt. Dürften alle dran rumwerkeln, dann fügt jeder nach gut Dünken hier und da was ein und wir haben den Salat: Viele Köche verderben den Brei.

Und vom Ansehen kann ich mir keine Brötchen kaufen, auch wenn Ansehen wirklich etwas sehr schönes ist. Dazu ist es zu viel Arbeit. Verdammt, jetzt habe ich schon einen Grund ausgesprochen, owbohl ich das gar nicht wollte.

> ich kann nicht für Fred und Freak sprechen.
Das ist klar. Aber selbst, wenn ich mich dazu bereit erklären würde, würde ich nicht eher anfangen, bis ich absolute Gewissheit und Zusage vom PB-Team hätte.

> dazu käme bestimmt noch, dass man dann auch mannigfaltig übersetzer bräuchte....
Nun, wenn ich das machen würde, würde ich sagen: Ich mach es erstmal auf Deutsch, das reicht. Ansonsten muss man hingehen und es erst einmal auf englisch (aber leicht verständlich) machen, damit alle was davon haben.
Wenn, sagen wir, ich, das Handbuch erarbeiten würde, dann würd ich vermutlich sagen: Hier habt ihr's auf Deutsch, macht was draus, ihr Übersetzer. Ich helfe euch, wenn ich Zeit erübrigen kann.


Aber, aber, aber... (Zumindest) Noch ist das hier alles reine Spekulation.

[Kaeru Gaman]

schau dir doch mal Mister-I-Wrote-A-Book old good-idea-teller Kale an.
http://www.purebasic.fr/english/profile ... ofile&u=34
hey, der Mann hat sich hingesetzt, und er hat ein buch geschrieben,
und er verdient kohle dran und Fantaisie verdient nix dran.

allein mit der übersetzung seines buches könntest du schon asche machen.
wenn du dich hinsetzt und sowas selber machst, um so besser.

aber Kale (und ich liebe ihn nicht, aber ich respektiere seine arbeit),
hat das nicht auf die beine gestellt, weil er nur rumgejammert hat,
sondern er hat sich drangesetzt und es getan.


> vom Ansehen kann ich mir keine Brötchen kaufen

verachte niemals den mentalen nutzen von Ansehen unter deinen mitmenschen.
ein guter Ruf bewahrt dich zwar nicht vorm Hungertod,
aber er wärmt in kalten nächten besser als eine wolldecke kombiniert mit verachtung.

....lass dir das von einem alten, verarmten Philosophen mal sagen...

[AND51]

Ich hab schon mal dran gedacht, wie's wär, wenn man ein Buch schreibt. Aber wie gesagt, es ist ein Haufen arbeit.
Ich orientiere mich dabei an meinem Perl Buch. Ich wüsste gar nicht, welche Themen ich behandeln sollte und auch nicht, ob ich gut darin bin, Dinge zu erklären.
naja wei dem auch sei, der Buchgedanke wird (höchst-)wahrscheinlich nur ein Gedanke bleiben.

[freak]

In meinen Augen hat PB eine gute Dokumentation (nicht super, aber gut genug)
Wer da anderer Meinung ist hat einfach noch keine schlechten Dokumentationen gesehen.
Hier ist meine top 3 der schlechtesten Dokumentationen mit denen ich arbeiten musste,
wer sich die angetan hat wird sich nicht mehr über die von PB beschwehren:

Platz 3: Gtk
Seit Version 2 erheblich besser geworden, aber immer noch sehr gering mit Informationen bestückt.
Um viele der nicht trivialen Teile zu verstehen ist man auf externe Tutorials und Beispiele angewiesen.

Platz 2: Scintilla
Mehr eine Ansammlung von Stichworten, den Rest muss man ausprobieren.

Platz 1: CarbonLib Dokumentation (OSX)
Sowas habe ich noch nie gesehen. An manchen Stellen ist lediglich der Prototyp einer Funktion angegeben,
mit je ein paar Worten zu den Parameter die sich praktisch aus dem Namen ergeben hätten
und sonst kein einziges Wort zur Funktion, nichtmal einen Satz was das Ding überhaupt soll!
Da erhält man also in der offiziellen Dokumentation nicht mehr Informationen als beim lesen der header Dateien,
und das ist immerhin die Dokumentation für die API eines kommerziellen Betriebssystems.


In der PB Dokumentation ist der komplette Befehlssatz beschrieben, manchmal ist ein Befehl etwas knapp erklärt, aber
spätestens beim Lesen der Informationen zum Rest der Library ergibt sich das.
Die Kapitel zu den Compilerfeatures sind viellecht manchmal etwas zu knapp, aber genau für sowas war der Thread hier ja gedacht.
An sowas wie die WinAPI Dokumentation kommt unsere Hilfe natürlich nicht ran, aber das kann
man von so einem Projekt auch einfach nicht erwarten. (Und die WinAPI docs gibt es auch nicht auf Deutsch wohlgemerkt!)
Übrigens denke ich das wir weit mehr Zeit in die Hilfe investieren als die meisten von euch denken.
Wer mal selber sowas geschrieben hat weiß wieviel Arbeit dahinter steckt.
Die QuellDateien der englischen Hilfe sind ca 1.5Mb reiner Text, das schreibt sich nicht mal so eben.


Ich stimme ts-soft zu. Es handelt sich hier um eine Sprachreferenz, kein Tutorial.
Die Beschreibung eines Befehls sollte knapp die (und nur die) Informationen liefern
die für diesen Befehl wichtig sind. Die Dokumentation mit unrelevanten Informationen zu
überladen mag dem Neuling ja erstmal helfen, jedem der sich aber ein bischen mit der Sprache auskennt
wird das nur im Weg sein bei der Suche nach den wirklich wichtigen Informationen.

Das Thema Unicode hat zum Beispiel beim Befehl ReadData() absolut nichts verlohren.
Der Befel ist zum lesen von binären Daten da, ob da jetzt strings drinstecken oder sonstwas
ist für die korrekte Beschreibung des Befehls irrelevant. Auch das bei der aktuellen Position in der Datei gelesen wird
sollte sich von selbst ergeben, spätestens wenn man sich die anderen Befehle der Lib ansieht. (über diesen Punkt kann man aber streiten denke ich)

Also, vielleicht doch die Anfängerfragen im Forum klären und ein bischen
filtern was ihr hier so postet, das ist für die Verbesserung der Hilfe hilfreicher...

[AND51]

Die Seite zu AddGadgetItem() sagt nicht, was 'Ergebnis' für eine Wirkung hat.

[Little John]

In meinen Augen hat PB eine gute Dokumentation (nicht super, aber gut genug)

Sehe ich auch so. Verglichen mit anderen Software-Dokumentationen die ich kenne, stufe ich die von PB als überdurchschnittlich gut ein. Mit 'ner schlechten Dokumentation hätte ich aber PB wohl auch nicht gekauft.

Wer mal selber sowas geschrieben hat weiß wieviel Arbeit dahinter steckt.

Jupp. Keine Frage dass da 'ne Menge Zeit drinsteckt. Und es wurde auch ziemlich sorgfältig gearbeitet -- was ich immer sehr schätze, was aber heutzutage leider relativ selten geworden ist. Vielen herzlichen Dank dafür!

Ein paar Änderungs-/Ergänzungsvorschläge habe ich allerdings schon . (Falls die bereits irgendwo auf den vorangehenden 40 Seiten besprochen wurden, bitte ich im Voraus um Entschuldigung.)

Die Hilfe enthält ja verschiedene nützliche externe Links. Wenn ich so einen Link anklicke, öffnet sich die externe Webseite aber innerhalb des PB-Hilfefensters! Das ist aus verschiedenen Gründen unpassend, es sollte der Default-Webrowser meines Systems gestartet werden, und die betr. Seite anzeigen. Um das zu erreichen, braucht in den HTML-Quelltext bei externen Links nur target="_blank" hinzugefügt zu werden, also z.B.

Code: Alles auswählen

externer Link
-------------
vorher: <a href="http://www.pipapo.de/">Guckst Du hier</a>
besser: <a href="http://www.pipapo.de/" target="_blank">Guckst Du hier</a>

Die gewählten Farben von Schrift und Hintergrund sind m.E. nicht gut. Das ist nicht nur eine Frage des persönlichen Geschmacks, so wie es jetzt ist ist einfach der Kontrast relativ gering. Nicht jeder PB-Benutzer ist unter 30 Jahren und hat eine Sehschärfe von 120%.

Entweder ich habe es komplett übersehen, oder es fehlt ein Abschnitt über die Parameterübergabe an Prozeduren (Pass by Value, Pass by Reference). Das ist ein sehr wichtiges Thema!
Für Programmieranfänger ist es wichtig, überhaupt zu beschreiben worum es dabei geht, und was beachtet werden sollte. Und auch fortgeschrittene Programmierer die neu bei PB sind, brauchen eine Referenz, mit welcher Syntax welche Variablen by Value bzw. by Reference übergeben werden.

PB macht ja offenbar "short-circuit evaluation" (Wie heißt das auf deutsch?), d.h. z.B. wird im folgenden Programm die Prozedut Test() nie aufgerufen, weil schon vorher klar ist dass die Bedingung nicht erfüllt sein kann:

Code: Alles auswählen

; PureBasic 4

Procedure.l Test()
   Debug "Huhu"
   ProcedureReturn 0
EndProcedure

If 1=0 And Test()=4
EndIf

Das finde ich auch sehr gut, aber wo ist es dokumentiert?

Wen Du möchtest, kann ich bei der PB-Dokumentation auch ein bisschen mithelfen.

Gruß, Little John

[PMV]

Der Kontrast in der Hilfe ist doch gut, heller Hintergrund, schwarze
Schrift. OK, die dunkelgrünen Links sind vielleicht nicht ganz so glücklich
gewählt, aber ich fänds schade wenns geändert wird ... irgend wie gehört
das Design schon für mich zu PB

Die Parameterübergabe war schon immer "Pass by Value" bei den
Zahlenvariablen und Strings. Seit PB 4.0 kann man auch Arrays und
LinkedListen übergeben, diese werden "Pass by Reference" übergeben,
das lässt sich aber glaub leicht durch die Beispiele in der Hilfe zu
"Procedure : End Procedure" herrausfinden. Ne Zeile dazu könnte aber
auch nicht schaden.

MFG PMV

[Little John]

Ich finde dass alles was die Parameterübergabe betrifft systematisch an einer Stele der Hilfe erklärt werden sollte:
- Was bedeutet Pass by Value?
- Was bedeutet Pass by Reference?
- Welche Auswirkungen hat die Wahl der Übergabeart auf mein Programm?
- Wie ist die Syntax für die Übergabe von Zahlen by Value?
- Wie ist die Syntax für die Übergabe von Zahlen by Reference?
- Wie ist die Syntax für die Übergabe von Strings by Value?
- Wie ist die Syntax für die Übergabe von Strings by Reference?
usw.

Gruß, Little John