Re: [Frunge] Fragen zur Dokumentation

[Arno Trautmann]

Tach!

Dennis Heidsiek wrote:
> ich hänge ja noch immer der optimiſtiſchen Hoffnung nach, bald mit den
> Repos ſinnvoll arbeiten (ſprich commiten) zu können, und deshalb habe
> ich damit begonnen, mir Gedanken über die Dokumentation unſerers
> Projektes zu machen. Dabei bin ich auf ein paar grundſätzliche Fragen
> geſtoßen, die ich gerne mit euch durchſprechen würde, bevor ich da
> irgendetwas commite (einchecke? puſhe?).

commiten oder pushen ;) Je nachdem, ob lokal oder auf den Server …

> 1.) In welcher Sprache – bzw. Schreibweiſe – ſollte die Dokumentation
> verfaſſt werden?
> 
> Ich würde hier grundſätzlich für das gleiche Vorgehen wie bei der »Linux
> Libertine« (oder auch bei Koma-Script«) plädieren, ſprich jeweils eine
> komplett engliſche und eine komplett deutſche Faſſung anzubieten.
> Natürlich beſteht hier (auch auf Grund unſerer beſchränkten Reſourcen)
> immer die Gefahr, daſs eine der beiden (wahrſcheinlich die engliſche)
> hinterherhinken bzw. weniger ausführlich ſein wird. Aber das finde ich
> nicht weiter ſchlimm, wenn darauf in der kürzeren Faſſung auf der
> Titelſeite hingewieſen werden ſollte.

Da bin ich gegen. Zumindest am Anfang wird sich die Doku häufig ändern –
und es gibt nichts Nervigeres (außer Zensur)¹ im Internet als veraltete
Doku. Ich wäre dafür, erst eine englische Doku in der Entwicklungsphase
zu schreiben. Wenn das Projekt in die Anwendungsphase übergeht und weite
Verbreitung gefunden hat, dann erst ist mehrsprachige Doku sinnvoll.

> Was die deutſche Faſſung angeht, ſtellt ſich die Frage, ob wir ſie mit
> oder ohne dem langen ſ (ſprich in »normalem«- oder Fraktur-Satz)
> abfaſſen wollen.

Ich würde sie als pdf ausgeben und in gebrochener Schrift. Sobald wir
eine haben ;)
Solange wir keine haben, Antiqua + ſ. Und ich werde mir demnächst den
ſ-Modus unter Linux ansehen …

> Meine diesbezügliche Meinung dürfte ich wohl mit dieſer
> E-Mail in dezenter Art und Weiſe klargemacht haben ;-). Auch wenn das
> nicht ausſchießt, Teile der Dokumentation (etwa die engliſche GDFL) in
> der Antiqua (ſprich Linux Libertine) und nur mit dem »normalen« s
> abzufaſſen. Solange wir noch keine fertige »Brotſchrift« haben, können
> wir auch für den geſamten Text die Linux Libertine nutzen (die ein ſ
> hat) und dann erſt auf eine Frunge-Schrift wechſeln – aber wer ſoll ſie
> einmal nutzen, wenn noch nicht einmal wir ſelbſt?

Unterschied zwischen Entwicklungsdoku und Anwenderdoku. Erstere muss
einfach nur lesbar sein, zweitere überzeugend. Daher dann in letzterer
eine Frunge, in ersterer irgendwas. Darf auch gerne nur der .tex-Code
z.B. sein, den dann der interessierte Nutzer setzen darf. Außerdem
spricht nichts dagegen, mehrere Versionen anzubieten – eben weil das mit
TeX ja so schön einfach geht :)

> Das einzige Argument,
> das meines Erachtens für eine vollſtändige Antiqua-Verſion ſprechen
> würde, wäre daſs die meiſten deutſchſprachigen Nutzer damit vertrauter
> ſein dürften. Aber wer ſich für gebrochene Schriften intereſſiert …
> außerdem ſollte es nicht ſo ſchwer ſein, irgendwann ein Skript zu
> ſchreiben daſs alle langen durch runde s erſetzt (da reicht ja wirklich
> ſchon ein einfaches »replace all«), um ſo zuſätzlich eine automatiſch
> generierte Verſion in Antiqua ohne das lange ſ (wer auch immer das leſen
> mag ;-)) anbieten zu könnten. Aber die umgekehrte Richtung wäre viel
> ſchwerer umzuſetzen.

Auch wieder per TeX einfach machbar: Intern das ſ für ein s verkaufen
und fertig ;)

> Ach ja, wir könnten rein theoretiſch natürlich auch ein dreiſpaltiges
> Dokument erſtellen (»Englisch, Deutsch, Deutſch«) und ſo alle drei
> Verſionen gleichzeitig anbieten ;-) – aber nein, das war jetzt kein
> ernſt gemeinter Vorſchlag.

Fände ich gar nicht soo dumm … Vllt. für kurze Texte oder so. Dann kann
man auch gleich Schriftbild, Laufweite etc. vergleichen. Und schauen,
womit man besser zurechtkommt.

> 2.) Welche Lizenz(en?) wollen wir für unſere Dokumentation wählen?

Habe mich noch nie mit Lizenzen befasst, von daher halte ich mich hier
raus …

> Ich ſehe hier derzeitig vier Möglichkeiten:
> • Wir machen es wie die Linux Libertine und laſſen dieſe Frage erſtmal
> offen (in der (Xe-)Libertine-Dokumentation konnte ich keinen
> Lizenzhinweís finden). Da bin ich dagegen.
> • Da wir von der Savanne gehoaſted werden, wäre die »GNU-Lizenz für
> freie Dokumentation 1.3« (GFDL) ſicherlich die naheliegende Möglichkeit.
> Dieſe Lizenz iſt zudem ſpeziell für dieſen Anwendungsfall (Handbücher
> etc.) konſtruiert worden. Allerdings gibt es auch Kritik an dieſer
> Linzenz, ſo wird ſie beiſpielsweiſe von Debian als unfrei² angeſehen.
> • Ich perſönlich ſympatiſiere hingegen ſehr ſtark mit der »modernen«
> CC-BY-SA 3.0 Lizenz, die auch im Neo-Wiki (und bald auch in der
> Wikipedia) zum Einsatz kommt und geringere (bzw. modernere)
> Anforderungen beim Zitieren ſtellt (etwa einen paſſenden Link zu ſetzen).
> • Als Kompromiſsvorſchlag wäre auch hier vielleicht wieder eine
> »Duallizenſierung GFDL/CC-BY-SA« (analog zu GPL/OFL bei den eigentlichen
> Schriften) denkbar.
> 
> Anmerkung 1: Weitergehende Argumente und Links zum Thema »GFDL vs.
> CC-BY-SA« finden ſich etwa auf dieſer Seite¹ des Neo-Wikis.
> Anmerkung 2: Ich beharre hier keinesfalls auf Düvel komm’ raus auf
> meiner perſönlichen Präferenz, finde aber daſs wir dieſe Frage
> entſcheiden ſollten.
> Anmerkung 3: Gut, daſs die Schriften (auch) unter der OFL ſtehen, ſonſt
> hätten wir wohl auch die Dokumentation unter die GPL ſtellen müſſen –
> was hier wohl nicht wirklich paſſen würde, oder?
> 
> 3.) In welchem Seitenformat ſoll die Dokumentation entſtehen?
> 
> Ich würde aus mehreren Gründen dafür plädieren, unsere Dokumenation im 
> A5-(und nicht im üblicheren A4-)Format zu ſetzen:
> • Es würde typographiſch geſehen beſſer ſein: Die Gebrochen Schriften
> haben einen ſehr hohen Grauwert (nicht umſonſt heißen ſie auf engliſch
> »Blackletter«) und eine enge Laufweite, ſo daſs man bei A4 übergroße
> Ränder wählen müſſte, um die Zeilen nicht zu lang werden zu laſſen. A5
> wäre alſo von der Satzſpiegelkonſtruktion³ her geſehen einfach die viel
> natürlicher Löſung.

Guter Punkt. Müsste man sich einfach mal ansehen. Prinzipiell ist gegen
einen breiten Rand aber auch nichts zu sagen; die großen Folianten
früher hatten immer sehr breiten Rand. Wären wir also in guter Tradition :)

> • Wie bereits in meiner »TeX Starthilfe«-E-Mail beſchrieben, würde es
> dem Nutzer auch ermöglichen, die Dokumentation als echtes Büchlein
> ſelbſt auszudrucken :-).
> • Außerdem iſt A5 Bildſchirmfreundlicher: Auf meinen 16/10-Bildſchirm
> kann ich bequem zwei Seiten nebeneinander leſen (ohne zoomen oder
> ſcrollen zu müſſen).

Sinnvoll.

> • Die Dokumentation zu Koma-Skript macht es etwa genauſo :-).

Die sieht aber nicht im Ansatz gut aus. Das ist nur eine Dokumentation,
die Informationen bieten soll. Gut lesbar ist erst die gedruckte
Variante. Das pdf würde ich mir für guten Stil nicht als Vorlage nehmen …

> • Und natürlich können wir trotzdem auch noch eine A4-Präambel der
> Dokumentation erſtellen, daſs iſt ja das tolle am Prinzip der Trennung
> von logiſchem Markup und der konkreten Formatierung in LaTeX :-).

Kommt ganz drauf an, was du willst: Sollen die Leser das ganze selbst
kompilieren oder ein fertiges pdf bekommen?

Aber gerade wegen der Trennung von Inhalt und Format wäre ich dafür, die
Frage nach dem Format zurückzustellen und erstmal Inhalte zu bekommen,
sprich: Glyphen!
Eine Doku ohne zu Dokumentierendes ist sinnfrei …

Gruſs
Arno

signature.asc
Description: OpenPGP digital signature