[linux-l] Warum gibt es keine einheitliche Dokumentation? (war: dwww)

Di Dez 26 01:04:26 CET 2006

Liebe Gruppe,

Detlefs letzte Mail hat mich zu weiteren Gedanken zum Thema freie
Software & Dokumentation inspiriert. Mich würde interessieren, was
ihr davon haltet und wie eure Erfahrungen so sind.

On Mon, Dec 25, 2006 at 11:44:27AM +0100, Detlef Lechner wrote:
> Ich möchte gern dwww benutzen, weil ich oft Dokumentation zu einem
> Debian-Befehl nicht finde, weil sie sich auf meinem Rechner irgendwo
> versteckt. Ich habe deshalb das Programmpaket dwww installiert.

Nunja, Debian versteckt die Doku nicht wirklich. Zunächst einmal hat
*jedes* Paket eine Manpage. Das ist eine feste Regel, die jeder
Debian-Maintainer zu befolgen hat. Hat der Software-Autor keine Manpage
geschrieben, muss der Maintainer eine schreiben. (mit entsprechenden
Tools, die z.B. "PROGRAMM --help" in Manpages umwandeln, sodass er eine
gute Vorlage hat und nicht alles per Hand machen muss)

Das heißt, unter Debian kommst du mit:
    man PROGRAMM
sehr weit, im Vergleich zu anderen Distributionen. Eventuell gibt es
noch Info-Pages:
    info PROGRAMM

Außerdem, wieder als feste Regel, hat jedes Paket eine Doku im
Verzeichnis:
    /usr/share/doc/PAKETNAME/
Mindesten eine README bzw. README.Debian ist da drin.

Natürlich sind 3 Stellen schonmal 2 zuviel, und ein Durchsuchen der
Gesamt-Doku ist ebenfalls kaum möglich. (mit einem kleinen Shellscript
aber zu schaffen ;-))  Ich wollte nur nochmals darauf hinweisen, dass
es unter Debian noch relativ "angenehm" ist. Wenn auch leider nicht so
super anwenderfreundlich.

In dem Zusammenhang könnte für dich interessant sein:
    http://www.penguin-soft.com/
Dort kannst du alle Manpages durchsuchen.

Schade eigentlich. Wenn die Distributionen die Dokumentationen genauso
vereinheitlichen würden wie die Softwarepakete ...

Andererseits gibt es ja bereits einheitliche Dateiformate. Es gibt
Manpages, nun gut, etwas beschränkt. Dann Info-Pages, die alles haben,
was man will. Ein guter Info-Pages-Browser mit Suchfunktion, der auch
Manpages behandeln kann, das wär's schon.

Aber nein, trotzdem muss ja unbedingt eine HTML-Doku geben. Und eine
Plaintext-README. Vielleicht noch ne PDF-Datei und ein ODT-Dokument.

Versteht mich nicht falsch: Sie werden ja nicht "einfach so" eingesetzt.
Sie lösen jeweils ein Problem. Aber sie packen es an der falschen Stelle
an:

Plaintext
---------
Man soll die wichtigsten Hinweise auch ohne Manpage-Reader
oder ähnlichem lesen können. Gut so. Aber das ist in Wahrheit ein
Problem des Manpage- und Infopage-Formats. Sie sind im Plaintext nicht
so gut lesbar. Besser wäre hier ein Wiki-Markup, aber auch die sind im
Plaintext mehr aufs Schreiben als aufs Lesen optimiert. Vergleiche zu
Perl drängen sich auf ;-). Eine gute Alternative wäre reStructuredText
(reST). Das sieht im Plaintext aus wie eine normale README. Dennoch
kann daraus gutaussehendes HTML und ähnliches generiert werden:
    http://docutils.sourceforge.net/docs/user/rst/quickref.html
    http://www-128.ibm.com/developerworks/xml/library/x-matters24/

HTML
----
In anderen Betriebssystemen kommt man mit HTML weiter als mit
Manpages und Infopages. Hinzu kommt, dass heutzutage ein Linux-Anfänger
eher den Browser kennenlernt als den Info-Viewer. Das mag zum Teil auch
daran liegen, dass Browser leichter zu bedienen sind und zudem auch noch
im Netz surfen können. Suchfunktionen im Browser hingegen sind grauenvoll,
dafür braucht man immer ein extra CGI-Script oder sowas. Außerdem sind
Browser immer "generisch" gehalten, hier könnten Infopage-Viewer
eigentlich ordentlich punkten, durch Handbuch-spezifische Features.

PDF
---
Hier kommt PDF ins Spiel. Die PDF-Viewer sind, was Bedienbarkeit
und Suchfunktion angeht, dem Infopage-Viewer und dem Browser überlegen.
Nachteil ist, dass hier nur eine "Druckversion" gezeigt wird, d.h. der
Text passt sich nicht der individuellen Fensterbreite und ähnlichem an.

ODT
---
PDF ist kein freies Format, ODT schon. PDF-Dokumente sind darauf
ausgelegt, einmal generiert und nie wieder geändert zu werden. Hier
kann ODT punkten. Es kann leicht erzeugt werden (OpenOffice, KOffice,
...) und fast überall hat man heutzutage OpenOffice. Konvertierung nach
PDF ist auch kein Problem, aber einige Paket-Bauer scheinen das als
überflüssig zu empfinden. :-(

Es werden jeweils Probleme gelöst, aber nicht der Gesamt-Kontext
beachtet. Das führt zu einem großen Haufen ungeeigneter Werkzeuge.
Ich kann zu Java, Python, ... Programmen eine API-Doc generieren
(JavaDoc, EpyDoc), aber das meistens nur nach HTML. Mit etwas Glück
auch noch nach LaTeX bzw. PDF. Ein kohärentes Stück Doku innerhalb
*einer* Software wird damit schon schwer gemacht. Ganz zu schweigen
von Einheitlichkeit über mehrere Software-Pakete hinweg.

Dabei könnte es so einfach sein. Man einige sich auf ein Standard-
Format für Dokumentationen. Zum Beispiel reST mit Zusatz-Empfehlungen
(Reihenfolge/Namen der Kapitel, etc.)  Meinetwegen auch MediaWiki-
Syntax, aber wenn man ein Wiki für die Doku aufsetzen will, kann man
auch gleich eines aufsetzen, das reST kann.

Sicherlich gibt es nun Probleme mit Grafiken, Formeln, etc.
aber MediaWiki hat's hinbekommen, und reST kann sicherlich auch
entsprechend erweitert werden. Für die meiste Software wird's reichen,
zumal die meisten Formeln und Schema-Skizzen eh erstmal als ASCII
beginnen. ;-)

Ich als Autor würde liebendgern die Doku einfach in die README
reinhauen, z.B. als reST. Das kann dann jeder Sven Guckes im Plaintext
betrachten. Für die Detlef Lechners unter den Anwendern werden dann
Manpages und Infopages daraus generiert. (*dürfte* eigentlich nicht
schwer sein)

Auch der Rückweg, Man/Infopage -> reST, erscheint mir nicht allzu
kompliziert (sogar leichter), sodass Projekte wie Debian, die für
alles ihre Manpages haben, auch nach reST umschwenken könnten, wenn
sie Interesse an einer großen einheitlichen Doku haben.

Für die Windows-User und die Projekt-Homepage wird dann noch HTML
erzeugt (gibt's bereits). Und nicht zu vergessen das PDF für's Web.
Der normale Benutzer würde seinen Info- oder reST-Viewer nehmen, und
aus diesem einfach direkt drucken. (intern wahrscheinlich über LaTeX,
DVI, PS, aber auch das gibt's AFAIK schon)

Was macht man bei API-Docs? Nunja, der perfekte Programmierer und
Dokumentator erklärt sein Programm in einem großen Text mit
entsprechenden Codeteilen. ("Literate Programming")  Diese Doku ist
didaktisch gut aufbereitet, sodass jeder ohne Probleme in den Code
hinein findet. Pro Funktionseinheit/Modul ein Unterkapitel, u.s.w.

Der normale Programmierer, wie ich, ist schon froh, wenn jede Funktion
einen nicht-trivialen Docstring besitzt. Also kommt ein API-Doc-Generator
her. Es wäre zu schön, wenn die Tools nicht blind nach HTML konvertieren
würden, sondern erstmal nach reST. Es ist ja schön, dass EpyDoc dem
JavaDoc nacheifern will, aber man sollte nur die guten Ideen kopieren.

Dann würde der Benutzer eine README und eine API-DOC sehen, die sowohl
im Plaintext gut lesbar sind, als auch im reST-Viewer. Die README könnte
sogar auf die API-DOC verweisen, oder diese inkludieren, aber das müsste
nichtmal unbedingt sein.

Fehlen noch die Linux-Howtos, z.B. das Linux Documentation Projekt:
    http://www.tldp.org/
Eine Schande, dass die nur per HTML verfügbar sind und nicht als Info-
Pages. Ja, sie sind auch noch als PDF und als Docbook verfügbar, aber damit
kann man noch weniger anfangen. Man sollten den Docbook-Bloat nach reST
konvertieren und per Wiki zugänglich machen. *Das* würde Mitarbeit anregen.

Es gibt ja auch viele Linux-Wikis im Netz, die ebenfalls genau diese
Vereinheitlichung versuchen, aber auf genau dem falschen Wege: Alles
nochmal neu schreiben. Es erscheint mir absurd, hier die selben Erwartungen
zu hegen wie bei der Wikipedia: Diese ist einzigartig. Linux-Dokus
hingegen gibt's zuhauf, und selbst die kleinste Manpage ist ein besserer
Ausgangspunkt als ein leeres Dokument.

Gerade die kleinen Wikis sollten bemüht sein, möglichst viel mit wenig
Manpower zu erreichen. Sie sollten in Effizienz und Automatismen
investieren. Selbst die überwiegend von Manpower getriebene Wikipedia
hat sehr viele Mechanismen. Natürlich auch wenn sie oftmal auch von ihrem Luxus
gebrauch macht, viele aktive Autoren zu haben. So kommt es, dass ihre
Anti-Spam-Mechanismen und -Empfehlungen für kleine Wikis einfach total
ungeeignet sind. Zurück zum Thema: Was ich stattdessen sehe, sind Linux-
und Howto-Wikis mit sehr einfacher Software, keinerlei Vorlagen oder
Wiederverwendung vorhandener (freier) Texte. Sie scheinen alle zu
hoffen, eine ähnlich große Autorenschaft wie die Wikipedia zu bekommen.
Stattdessen erschaffen die meisten es gerade so, die Anfänger zu
ermutigen, für andere Anfänger zu schreiben.

Zusammenfassend haben sind das also wirklich drei verschiedene Lager,
die alle ihre eigenen Interessen und ihre eigenen Sprachen haben:

Linux Documentation Projekt (LDP)
---------------------------------
    - gute Howtos, FAQs, ...
    - schlechtes Dateiformat (SGML/XML) als "Quellcode"
    - motiviert nicht zur Mitarbeit, vorallem nicht zur Mitarbeit von
      Anfängern, obwohl *hier* gerade das fehlt.

Linux-Wikis
-----------
    - viel zu viele
    - fachlich schlechtere Dokus
        (z.T. Halbwissen, z.T. falsch, siehe
         http://wiki.njh.eu/Gesundes_Misstrauen#Internetseiten)
    - dafür leichter verständlich geschrieben
    - keine Wiederverwendung der LDP-Sachen
    - motiviert hauptsächlich Anfänger zum Schreiben, obwohl *hier*
      die Mitarbeit von Profis interessant wäre.

Manpages/Infopages der Software-Autoren
---------------------------------------
    - haben größtes Potential
    - sind nur dann gut, wenn das Dokuteam mit zum Projekt gehört
    - hat nur dann gute Howtos, wenn die User mithelfen
      bzw. der Autor auf die User hört

Es fehlt eine gemeinsame Sprache. Und ein gemeinsames Projekt, das
*alle* Aspekte berücksichtigt:
    - Autoren (Manpages)
    - fachkundige Dokuschreiber (LDP & Co.)
    - Anfänger (Linux-Wikis & Co.)
Dann kann nämlich etwas daraus werden. Für keinen Fachmann ist es
erstrebenswert, irgendwelche Fehler in irgendwelchen der Heerscharen
von Howtos zu korrigieren. "Gehören" die Howtos jedoch zum Projekt,
ist die Hemmschwelle geringer, man sieht einen größeren Sinn darin.
Kein Anfänger kann zu den LDP-Sachen wirklich etwas beisteuern. Die
Docbook-Sachen sind böhmische Dörfer für ihn. Dabei sind Doc-
Verbesserungen mindestens genauso wichtig wie Code-Verbesserungen
(Patches), wenn nicht sogar wichtiger. Und leichtverständliches
Schreiben gehört dazu, genauso wie ein Code-Cleanup.

Auch wenn dwww mehr eine Notlösung ist, weil es auf den wirklich
untersten gemeinsamen Nenner reduziert: HTML, macht es eine Sache
richtig: Es ist ein Automatismus, ein Mechanismus. Und kein Projekt,
das erst dann überhaupt brauchbar ist, wenn es viele Mannstunden vieler
Schreiberlinge gefressen hat. Und es skaliert sehr gut: Neue Dokus von
neuer Software werden ohne Aufwand mit eingebunden.

Dieses Prinzip ist sehr schön formuliert in den "FreeBSD Architectural
Guidelines", Regel 7, Satz 1:
    "Provide mechanism, rather than policy."

Es fehlen im Moment einige wichtige Mechanismen (z.B. Konvertierung
von Manpages, Infopages, etc.), und vorallem fehlt ein Mechanismus,
wie Doc-Verbesserungen dem Autor zurückfließen, denn hier ist der
"klassische Weg" über E-Mails mit Patches oder Bugtracking-Systeme
nicht ratsam.

Auch die Einbindung externer Systeme, etwa der Manpages und Infopages,
wäre wichtig. Solange die Autoren das neue System nicht direkt
unterstützen, muss es sich.

Wo sollte solch ein Projekt liegen? Nunja, entweder bei einer großen
freien Freie-Software-Distribution (Debian, Gentoo). Oder beim einem
Freie-Software-Dokumentations-Projekt wie LDP. Kleine Sachen wie das
Unbunto-Wiki wären weniger geeignet als Ort, obwohl deren Unterstützung
natürlich unerlässlich wäre. (z.B. könnte das Ubuntu-Handbuch diesem
Projekt anvertraut und dort gepflegt werden ... von den gleichen Autoren
gepflegt, aber unterstützt durch eine größere Community, und mit der
Möglichkeit, die nicht-Ubuntu-spezifischen Teile auszulagern)

So, das waren erstmal meine Gedanken zu dem Thema. Mich würde
interessieren, wie ihr darüber denkt.

Viele Grüße,

    Volker

-- 
Volker Grabsch
---<<(())>>---
Administrator
NotJustHosting GbR