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

[Volker Grabsch]

On Thu, Dec 28, 2006 at 05:36:43AM +0100, Steffen Dettmer wrote:
> * Volker Grabsch wrote on Tue, Dec 26, 2006 at 01:04 +0100:
> > Schade eigentlich. Wenn die Distributionen die Dokumentationen genauso
> > vereinheitlichen würden wie die Softwarepakete ...
> 
> Hier bin ich anderer Meinung... Klappt IMHO nicht mal bei den
> Softwarepaketen!
> 
>   Vereinheitlichen, naja... Das einzige einheitliche ist doch RedHats RPM,
>   was SuSE auch nimmt; was natürlich nicht heisst, dass ein SuSE RPM bei
>   RedHat funktioniert oder umgekehrt (oft nichtmal bei source RPMs, selbst
>   wenn die source tarballs laufen - spätenstens beim rcscript klemmts
>   dann).

Stimmt, SuSE und RedHat sind schlechte Beispiele. Ich meinte vorrangig
Debian und heutzutage auch Gentoo. Oder FreeBSD.

Die machen ziemlich viel mit den Paketen. Gerade Debian ist für seine
vielen Policies bekannt, sowohl was Source als auch Binary-Pakete angeht.
Compiliert ein Source-Paket z.B. in der Build-Farm auf einer einzigen
Architektur nicht, dann ist das ein harter Fehler und der Maintainer
kann es nicht hochladen. Er muss dann explizit im Paket angeben, auf
welchen Platformen es compiliert und auf welchen nicht. Ähnliches gilt
für fehlerhafte Dependency-Einträge.

Diese Strenge hat aber nicht nur Vorteile.

Naja, andere können hier sicherlich mehr darüber erzählen. Ich habe nur
mal einen ca. 2monatigen Kurzausflug in diese Welt gemacht, und bin kein
Debian Maintainer oder sowas.

> > 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.
> 
>   "info" kann ja man pages, aber die Suche ist entweder nicht gut oder ich
>   glaube das nur, weil ich info ja nicht bedienen kann.

"info" kann bei Manpages nichtmal die Links weiterverfolgen. Na gut, "man"
kann das auch nicht.

Bei Infopages hingegen kann man mit "info" via Tab zum nächsten Link
springen oder mit den Cursortasten dahin navigieren. Dann mit ENTER dorthin
springen. So ähnlich wie in w3m oder lynx.

> > Aber nein, trotzdem muss ja unbedingt eine HTML-Doku geben. Und eine
> > Plaintext-README. Vielleicht noch ne PDF-Datei und ein ODT-Dokument.
> 
>   Zunächst ist HTML eigentlich egal. Man möchte einen Browser benutzen.
>   Hier ist komischerweise nicht unbedingt Unterstützung für einfache
>   Formate da (selbst wenn der Browser HTML, XML, CSS und Javascript kann).
>   Weiterhin heisst HTML ja auch nicht viel (kann lesbar sein oder
>   schlechte Farben haben, zu kleine Schriften vorschreiben etc).

Genau das ist ja das Problem. HTML ist zu "flexibel". Keine
Einheitlichkeit, keine Trennung von Inhalt und Form. Dabei sollte es
doch gerade bei Handbüchern möglich sein, ein halbwegs einheitliches
HTML-Format zu definieren (und sei es nur implizit durch
man2html-Werkzeuge ;-)), für welches man dann CSS-Stylesheets sammelt.
Wenn einer seine Doku schön macht, profitieren dann auch alle anderen
davon. Naja, so einen ähnlichen Traum hatte ich auch mal auf meiner
"Wikidok"-Seite geäußert.

[reST]
> >     http://docutils.sourceforge.net/docs/user/rst/quickref.html
> >     http://www-128.ibm.com/developerworks/xml/library/x-matters24/
> 
> Das sieht in der Tat ziemlich cool aus, find ich! 
> 
>   Man könnte es auch in Terminals mit bold/underline oder
>   Farbunterstützung im Textmodus rendern (wie man das ja auch macht).

Texterzeugung gibt es sogar. Farbe oder fett/unterstrichen glaubich
nicht.

>   Sowas in der Art wäre vielleicht wirklich fein; müsste sich aber
>   natürlich erst zum "Standard" mausern, damit es zum "Standard" wird :)

Es wird aktiv in Python-Quellcode und -Dokumentationen eingesetzt und
ist dort bereits als Standard definiert. Sogar in den
Programmier-Richtlinien darüber, wie man Docstrings zu formatieren hat.

>   Zu Deinen "Plaintext" Beispielen: Wiki-Markup OK. Manpages sind auch
>   meiner Meinung nach im Plaintext kaum lesbar.

So schlimm sind sie nun auch wieder nicht.

>   HTML und XML behaupten von
>   sich auch, genau das zu sein: menschenlesbar, auch ohne Interpreter.
>   Dass das ein Marketing Gag ist, weiss man inzwischen hier und da...

HTML/XML ist z.T. schlimmer als Manpages. Zumindest kann man viel
schlimmeres Zeug damit produzieren. Einfaches HTML mit Nur-Inhalt
(sodass sich CSS um die Details kümmert) hingegen kann auch sehr
angenehm zu lesen sein. An Wikis oder reST kommt es natürlich dennoch
nicht heran.

>   Jedenfalls darf man BBCode nicht vergessen - kennen bestimmt sehr viele
>   Leute, die in Foren unterwegs sind. Interessant fand ich:
>   http://en.wikipedia.org/wiki/Comparison_of_lightweight_markup_languages
>   bei dem das IMHO sehr technisch-HTML-lastige BBCode erstaunlich schlecht
>   abscheidet. Das hat mich jedenfalls überrascht. Dachte, BBCode ist so
>   menschenunfreundlich, weil es so HTML ähnlich ist und so viel kann. Tja,
>   da hab ich mich geirrt.

Nö, das ist nur, damit man nicht in die Versuchung kommt, das Zeug
direkt an den Browser zu senden. Stattdessen ist der Programmierer
gezwungen, es zu parsen und nochmals als HTML auszugeben. Ein etwas
eigenwilliger Weg, um XSS-Attacken vorzubeugen.

> Das schöne an plain-Text ist, dass man sich das Betrachter-Tool
> aussuchen kann. Ich nehm oft vim, weil ich den ein bisschen bedienen
> kann.

Tipp: vim -R
So kannst du die Datei nicht ausversehen ändern. Ein :w! oder
ähnliches funktioniert natürlich trotzdem.

> > 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.
> 
> Ich finde, man sollte zwei "Arten HTML" unterscheiden. Einmal HTML, was
> z.B. Menschen benutzen, um Informationen zu strukturieren (und über CSS
> darstellen). Zum anderen das eher automatisch erstellte HTML, was
> eigentlich eher ne Visualisierungsschnittstelle ist (und am liebsten
> Pixelkoordinaten benutzt, 800x600 und bloss nicht drucken).

ACK. Aber selbst das "einfache HTML" kannst du kaum per Standard
durchdrücken. Und solange du das nicht kannst, kannst du auch keine CSS-
Dateien wiederverwenden, und macht ne Menge zunichte.

Dann doch lieber reST, man, etc. als Standardformat, und HTML generieren
lassen, das unseren Vorstellungen entspricht.

> > PDF
> > ---
> > Hier kommt PDF ins Spiel. 
> 
> (bei PDF kommt PDF ins Spiel - in der Tat überraschend ;))

Ich bezog mich auf den letzten Satz des HTML-Kapitels:
> > hier könnten Infopage-Viewer
> > eigentlich ordentlich punkten, durch Handbuch-spezifische Features.

Denn PDF bietet eben diese Handbuch-spezifischen Features.
(Suche im gesamten Dokument, Druckversion, Kapitelübersicht, ...)

> > Es werden jeweils Probleme gelöst, aber nicht der Gesamt-Kontext
> > beachtet. Das führt zu einem großen Haufen ungeeigneter Werkzeuge.
> 
> Die Frage ist meiner Meinung nach aber nach wie vor, ob man denn das
> "Gesamt-Kontext" Problem überhaupt (mit einer Lösung) lösen kann, oder
> ob man gerade verschiedene Lösungen braucht.
[...]
> Ich glaube, es gibt mehrere Anwendungen von Dokumentation und Bedarf für
> mehrere Werkzeuge.

Auch die "verschiedenen Lösungen" sollten einem gemeinsamen Konzept
folgen, das sicherstellt, dass ihre Kombination wirklich das
Gesamtproblem abdeckt und dass es möglichst wenige Barrieren zwischen
ihnen gibt, bis auf die konzeptuellen, die man eh nicht weg kriegt.

>   Da gibt es mindestens Problemorientierung ("Ich will jetzt Problem X
>   lösen"), Lernen ("Wie funktioniert eigentlich Technologie Y") und
>   Nachschlagen ("wie war der Parameter zum Sortieren gleich").

So verschieden sind die nicht. Zum Beispiel besteht eine Howto nicht
nur aus Anweisungen, sondern auch aus der Erklärung, warum welche
Option in diesem Zusammenhang wichtig ist. Und wie man eventuell auf
anderem Wege ebenfalls zum Ziel kommt. Damit ist ein Teil des "Lernen"
schon in der "Problemorientierung" mit drin.

Weiterhin kannst du "Lernen" und "Nachschlagen" zusammenfassen. Denn
wenn du eine Option nachschlägst, brauchst du auch ihren Erklärungstext.
Dieses Zusammenspiel leisten bereits die Manpages. Hier sollte man eher
die vorhandenen Manpages verbessern, und kein extra "Nachschlagewerk"
oder externe "Einführungen" zu produzieren.

>   Es gibt etliche Doku-Arten, die mehr oder weniger gut zu den
>   Anwendungen passen. FAQs sind oft problemorientiert, man pages oft zum
>   Nachschlagen. Zum Lernen gibt es vielleicht ein Buch. Wikis sind
>   irgendwo zwischen Nachschlagen und den anderen beiden usw.

Eben. Das ist zu viel des Guten. Die ohnehin schon knappen Resourcen
werden verschwendet statt gebündelt. Synergie-Effekte werden im Keim
erstickt.

>   Weiterhin unterscheidet sich Dokumentation ja in der Zielgruppe
>   (Entwickler, Administrator, Benutzer, "Poweruser", "Gelegenheitsnutzer",
>   "Quereinsteiger", "Newbie" usw.) und damit im Niveau und Fokus.

Das ist in der Tat ein Problem. Lösungsvorschläge?

Zum Teil wird das Thema selbst in den uralten Manpages schon angegangen.
Es gibt eine Einleitung, die Optionen, und darunter weiterführende
Infos für die, die's interessiert. So kann jeder bei jedem Tool
individuell entscheiden, wie tief er in die Materie eindringen will.

Einziges Problem: Meistens sind nichtmal die Einleitungen anfänger-
freundlich. Das liegt meiner Meinung nach zum Teil aber auch an den
Werkzeugen, da es z.B. keinen Anreiz für einen Anfänger gibt, eine
Manpage so abzuändern, dass sie der nächste Anfänger mit weniger
Schwierigkeiten versteht. Eigentlich ein Unding im Zeitalter der
Wikis, "social networks", etc.

>   Auch
>   allgemeine und spezielle Dokumentation könnte man unterscheiden. Das
>   (also die Doku) lässt sich nichtmal baumartig einordnen...

Gut, aber gemeinsame Manpages für mehrere Tools, du nennst es "allgemeine
Dokumentation", gibt es doch. Es sollte vielleicht mehr davon geben.

> > 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.
> 
> Tja, fragt sich, wo reST dann wieder klemmt. Ein Buch kann man damit
> sicher auch nicht schreiben - also irgendwo ist halt eine Grenze.

Ja, aber es ging ja um eine Doku. Und natürlich kann man die auch nach
LaTeX bringen und als PDF drucken. Der Perfektionist (z.B. ich :-))
würde dann am LaTeX-Code noch letzte Schönheitskorrekturen per Hand
vornehmen. Aber das meiste macht LaTeX doch richtig[tm].

Schrott ist meiner Erfahrung nach eher erzeugt, wenn LaTeX-Code von
Menschenhand geschrieben wird, und zwar mit zu wenig LaTeX-Kenntnissen,
sodass die Dinge zu kompliziert gemacht werden.

> > Sicherlich gibt es nun Probleme mit Grafiken, Formeln, etc.
> > aber MediaWiki hat's hinbekommen, und reST kann sicherlich auch
> > entsprechend erweitert werden. 
> 
> So ein Wiki ist aber eben nicht portabel, verfügbar oder einfach
> installierbar!

Du hast mich falsch verstanden. Ins Paket kommen natürlich Textdateien
und ein Reader, der ggf. auch HTML oder PDF daraus erzeugen kann
(obwohl anzeigen und drucken ja auch schon reicht).

Ob der Reader intern so funktioniert, dass er HTML erzeugt und einen
Browser aufruft, oder ob der Reader ein CGI-Script ist, oder ob der
Reader wirklich ne eigenständige Applikation mit eigenem Renderer ist,
sei mal dahingestellt.

Das Wiki war für die Projektseite gedacht. So kann dann jeder etwas
daran ändern, wenn er online die Doku durchgeht. Vielleicht erlaubt auch
der Reader "Änderungen", die er nicht lokal speichert, sondern als
sauberen Patch an die Mailingliste des Projektes sendet, oder dort ins
Wiki einfügen lässt, oder was auch immer. Lokal soll das Wiki natürlich
nicht laufen, das wäre etwas witzlos.

>   Kannste nicht mal "fix eben installieren", wikimarkup -> PDF gibts
>   vielleicht nicht, wikimarkup -> console oder einfachem Drucker (ESC/P2
>   oder sowas) gibt's vielleicht nicht usw.

Konvertierung nach HTML und nach LaTeX wird gebraucht. Richtig. Hatte
ich das nicht geschrieben?

>   Ich finde Wikis zum schnellen Infos sammeln gut. Aber am Ende sollte
>   man die "stabilen" Infos nach zwei, drei Masteredits
>   "herrausrefakturieren" und in ein Dokument schreiben (PDF). Da geht's
>   wieder los: Dann haste ein Benutzerhandbuch, ein
>   Administrationshandbuch, eine Referenz, ein Lehrbuch und so weiter.

Diese "Herausfaktorisierung" ... wieso werden nicht einfach die Infos
direkt im Wiki umgestellt? Dann kann es immer noch nach PDF oder
sonstwohin konvertiert werden, aber die Community kann weiterhin daran
arbeiten, und direkt auf deiner neuen Strukturierung aufsetzen.

Dieser harte Schnitt, den du da machst, scheint mir unnötig.

> Für GUIs sind Bilder (von Dialogen) eventuell wichtig, aber kaum in
> plain text hinzukriegen (geht natürlich; z.B. über die reST Tabellen
> ginge ja sehr viel zu machen).

Ja, Bilder und Formeln sollten IMHO *immer* auch im Plaintext vorliegen,
soweit möglich/sinnvoll. Außerdem noch als Grafikdatei oder
LaTeX-Schnipsel. Inwieweit das von reST unterstützt wird, weiß ich
leider nicht. Einbindung eine Grafik durch Angabe des Dateinamens
sollte aber irgendwie möglich sein.

> > Ich als Autor würde liebendgern die Doku einfach in die README
> > reinhauen, z.B. als reST. 
> 
> > 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.
> 
> (PDF fürs Drucken, oder?)

Ja. Für die Windows-User. Die Unix-Benutzer hätten ja dann den tollen
reST-Viewer, von dem aus sie auch drucken können.

(... was intern wahrscheinlich ebenfalls via LaTeX gehen würde, dann
aber LaTeX->DVI->PS->Drucker statt LaTeX->DVI->PS->PDF. Das Paket
"latex-mk" kann ich da nur empfehlen, das bindest du in dein Makefile
ein, definierst eine oder mehrere Variablen, und schon hast du ein
fertiges sauberes Makefile für alles, was du jemals aus LaTeX erzeugen
willst.)

> Falls dass denn so geht! Ich glaube das eben nicht.
> 
> Ich glaube, wenn man Doku wirklich für den Menschen schreibt, muss man
> sich wohl mehrfach und redundant schreiben (je nach Zielgruppe etc).

Geht das nicht über verschiedene Detail-Levels zu regeln? Zusätzliche
Kapitel und zusätzliche Absätze innerhalb der Kapitel?

>   Hier sind wir wieder beim Thema, was wir neulich hier schon hatten:
>   wie sieht gute Doku an sich eigentlich aus und wie kriegt man sowas
>   hin.

Das ist die große Frage. :-)

>   Einige frühe Mitglieder von SelfLinux waren ja sogar bereit, Sachen
>   doppelt zu schreiben und sich die Arbeit zu machen, aber es liess sich
>   troz etlicher Anstrengungen dann doch nicht realisieren. Da steckt
>   dann doch ganz schön was dahinter, was man machen müsste...

Kann ich mir vorstellen. Aber die Mannstunden sind wertvoll, daher
sollte es einen Mechanismus geben, der eben keine doppelte Schreibarbeit
verursacht.

>   Ich glaube nicht, dass das alles sooooo verkompliziert wurde und man
>   alle Probleme am Ende mit einen plain-text-format erschlagen könnte...

Wer weiß ... wäre natürlich die Krone der Ironie, dass gerade die
freiwillige Mehrarbeit zu mehr Arbeit führt. Aber so ist das nunmal
mit der Mehrarbeit. Sie verleitet zur Redundanz. Diese führt zu
Inkonsistenz und damit zu mehr Arbeit.

> Am Ende ist auch "Wartung" ein Riesenproblem. 
> 
>   Bei GUIs verringert sich der Dokuaufwand, da GUIs i.d.R. im Vergleich
>   nur wenig können (neulich hatten wir das Beispiel mit der
>   Dateisuch-GUI, die mit drei Strings und vier Buttons auskommt.
>   Beschreibt man auf einer Seite. man find hat aber schon 555 Zeilen...
> 
>   Davon geht Doku auch mal kaputt

Kaputt? Nein, sie ist nur in die GUI geflossen. Wenn man sich durch
bessere GUI-Gestaltung die Hälfte der Doku sparen kann, ist das doch
ein Gewinn für beide Seiten, Programmierer *und* Anwender. Und wenn
die Software so intuitiv ist, dass die Doku nur noch 3 Sätze braucht,
umso besser!

>   (endet dann in einer Auflistung der
>   GUI Elemente. Dann steht da "Bei `Modus' wählen Sie den Modus aus."
>   usw.).

Sowas darf nicht in der Doku stehen. Das ist, als ob du in C schreibst:

| size_x ++;   // increments size_x

statt den Sinn der Inkrementierung zu notieren.


Oder als ob du auf ner Internetseite schreibst:

| ... müssen sie sich einloggen. Zum Einloggen clicken sie *hier*.

statt gleich das Wort "einloggen" zu verlinken:

| ... müssen sie sich *einloggen*.



Die Aufgabe von GUIs ist es doch gerade, dass man die nötigen Parameter
ohne Lesen der Doku zusammen kriegt. Außerdem gibt es noch schicke "tool
tips", mit denen man noch 2-3 Sätze hinzu packen kann, die genauer
erklären, was dort eingetragen werden muss, wenn man mit der Maus drüber
bleibt. Glade macht das z.B. recht gut.

Genauso habe ich nie den Sinn von Screenshots bei Eingabefenstern
gesehen. Okay, bei Ausdrucken, oder bei Listen-Übersichten, da ist
es sinnvoll, weil der Kunde so Beispiel-Daten sieht. Ein Beispiel-
Datensatz für das Programm ist dann aber vielleicht sinnvoller.


>   Tolle Beispiele finden sich im MS Project Buch von MicroSoft
>   Press. Hier steht sowas wie "Zum Schliessen des Fensters drücken Sie
>   den `Schliessen'-Button". Sicherheitshalber gibts auch noch einen
>   Screenshot mit dem `Schliessen'-Button...

Sowas ist grauenvoll. Das gehört dort einfach nicht hin. Dass "++"
einen Wert inkrementiert, schreibt man in ein C-Tutorial, aber nicht
in eine C-API-Doc. Dass man auf Links draufklicken kann, schreibt ein
Provider auf seine Startseite für die Neulinge, aber diese "Info"
gehört nicht auf eine Homepage. Und genauso gehört die Info, dass ein
Label das entsprechende Textfeld beschreibt, in die Windows-Anfänger-
Anleitung, wenn überhaupt. Oder in einen Computer-Anfängerkurs. Aber
keinesfalls in eine Howto für ein konkretes Programm.

Ein großes Doc-Projekt kann sich daraus retten, indem es die gemeinsamen
Grundlagen mehrerer Programme in entsprechende Seiten auslagert. Oder
in eine Fußnote beim Druck-Dokument. Bei Webseiten sind Fußnoten IMHO
affig, dafür gibt's doch "Hover Text" oder "Tool-tips" oder wie sich
das schimpft.

Wenn man beim Benutzer wichtige Grundkenntnisse nicht voraussetzen kann,
sollte man damit IMHO nicht die Doku bloaten, sondern dieses Grundwissen
separat vermitteln. Das erhöht auch die Wiederverwendbarkeit.

> > 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)
> 
> Wie schön könnte man einen aus plain-text automatisch erzeugten Druck
> überhaupt hinkriegen? Brauchbar?

Wie schon gesagt: LaTeX. Wo ist das Problem?

>   Ich glaube, im jedem Dokument gäbe es dann eine Stelle, die in
>   mindestens einem Format schlecht ist. Entweder hat das PDF ne Macke oder
>   der info-Viewer macht was komisches. Für richtig "schöne" Drucke ist das
>   wohl nur sehr bedingt geeignet.

Im Gegenteil, *gerade* automatisch generierte Doku haben noch die besten
Chancen.

>   Man möchte ein Inhaltsverzeichnis, einen Index und so weiter.
>   Vielleicht möchte man auch 

... möchte man auch was? Dein Satz bricht einfach ab.

Davon abgesehen: Kapitel kann reST doch. Diese automatisch zu
nummerieren und ein Inhaltsverzeichnis draus zu machen: In LaTeX
passiert's automatisch. Die HTML-Generatoren erzeugen sowas ebenfalls,
sogar entsprechend verlinkt.

Natürlich braucht man immer Markup. Aber Plaintext-Markup wie in
Wiki-Sprachen oder "unauffälliges" Markup wie in reST sind auf jeden
Fall angenehmer als jedes künstliche, explizite Markup (wie in LaTeX, XML).

> > 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. 
> 
> Ein Wiki funktioniert aber nur mit Historie. Bei READMEs will ich keine
> solche (höchsten im CVS, aber das ist was anderes).

Das Wiki soll auf der Projekt-Homepage liegen. Und gerade *da* sollte
doch beides identisch sein: Das Wiki sollte direkt die vorhandene
Versionskontrolle nutzen, statt einer eigenen, separaten. Code und Doku
in einem gemeinsamen Repository. Und es sollte egal sein, ob man ein
bestimmtes reST-Dokument nun per Wiki bearbeitet, oder mit dem vim und
dann ein "cvs commit" macht.

Übrigens würde ich lieber zu Mercurial raten. Oder wenn's zentralisiert
seinn muss, dann Subversion. Aber reiße dich, wenn möglich, von CVS los!
Damit habe ich früher angefangen, mannomann, was das vorallem für ein
konzettueller Ballast ist, den man immer mitgeschleift hat ... bei jeder
Aktion, die kein commit oder update war, sondern irgendwas mit Braches
oder Releases zu tun hat. Selbst als geübter CVSler wusste ich
Subversion sehr zu schätzen, Darcs und Mercurial umso mehr.

> > *Das* würde Mitarbeit anregen.
> 
>   (Foren regen auch zur Mitarbeit an - mit dem Ergebnis, dass google
>    kaum noch benutzbar ist...) 

Wikis sind keine Foren. Du vergleichst Äpfel mit Birnen. Ein Forum
wird zur Müllhalte, weil jeder nur etwas hinzu kippen kann. Eine Wiki-
Seite hingegen ermöglicht Änderungen, Ergänzungen und Kürzungen des
Geschriebenen.

Sicher, es gibt auch viel Müll, der in Wikis steht, aber selbst dort
sind die Diskussionsseiten die Müllhalde, wären auf den eigentlichen
Seiten sich von Zeit zu Zeit immer mal wieder jemand findet, der
aufräumt ... was bei Wikis viel angenehmer ist. Dort ist die
Hemmschwelle auch viel geringer als in einem Forum, wo man erstmal alles
neu zusammentippen/kopieren darf, umformulieren muss, etc.

> > 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. 
> 
>   (Na ja, da wird oft und gern abgeschrieben! Wahnsinn ist das. Dann
>   wird geändert und alles spaltet sich auf. Eine Katastrophe. Am Ende
>   wartet man einen Text in 20 Wikis, aber vermutlich überleben nur 3 das
>   nächste Jahr :))

Ich habe auch ein eigenes Wiki. Aber wenn mein Text in ein anderes Wiki
passt (war bisher nur einmal der Fall), schreibt ich es stattdessen dorthin.

Meine eigene Homepage verlinkt dann auf alle Seiten, die ich geschrieben
habe bzw. an denen ich mitgewirkt habe. Egal, ob im eigenen oder in
einem fremden Wiki. Funktioniert soweit recht gut.

> > 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.
> 
> Ich weiss nicht, ob man Anfänger *schreiben* lassen möchte, oder lieber
> Kommentare und Fragen von ihm bekommt. Ein Anfänger kann sowas nicht
> unbedingt schreiben, nee.

Moment, ich meine hier nicht unbedingt Computer-Anfänger. Ein Anfänger
auf dem einen Gebiet kann auch ein Profi auf einem ganz anderen sein.

Wenn jemand aus dem Kernel-Umfeld das Python-Tutorial didaktisch
schlecht findet, endlich herausgefunden hat wie's geht, wieso sollte
er dann den Text nicht umschreiben? Vielleicht hat er sogar in Sachen
Dokumentation mehr drauf als der ursprüngliche Autor.

Genau solche Vorurteile oder pauschaulen Abgrenzungen gegenüber Hilfe,
die man "eh nicht braucht", sollten mit der Zeit abgebaut werden. Sicher
gibt es Leute, die besser nicht dort hinein schreiben, sondern nur
Hinweise geben können. Aber das gibt es immer, und es können genauso
gut Leute mit Durchblick sein, die trotz allem schlechte Schreiber sind.

> > 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
> 
> Die beiden Punkte finde ich wichtig und richtig, volle Zustimmung.
> 
> Es ist ideal, wenn einer aus dem Team, die was entwickeln, das auch
> beschreibt. Das ist nicht auf Software-Autoren beschränkt, gilt
> insbesondere auch für Konzepte.

Die Hilfe der Anwender brauchen sie dennoch in jedem Fall. Ein Autor
schreibt für die Leser. Woher will er wissen, ob er sie tatsächlich
erreicht? Sind Kritiken und Forenbeiträge wirklich ausreichend, oder
bieten die Werkzeuge der modernen Kolaboration (Wikis & Co.) nicht
noch ganz andere Möglichkeiten, die man auch nutzen sollte?

> > 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.
> 
> Ja, prima.
> 
> ich glaub, es ist weniger wichtig, ob nu HTML oder PDF rauskommt, wenn
> die Doku intern überhaupt erstmal gut und konsistent etc. ist.

Meine Worte.

Jedoch ist technische Konsistenz die Voraussetzung für inhaltliche
Konsistenz.

> Aufgabe
> der Distributions-(Paket-)Maintainer wäre dann, diese zu referenzieren
> (was Debian ja wohl überdurchschnittlich gut macht).
> 
> Ich glaube, dass das aber nicht ausreichend ist.
> 
>   Ich kann perfekte API Doku über WLAN haben, jede Kommandozeilenoption
>   supergenau beschrieben haben - aber dennoch nicht wissen, dass ich bei
>   SuSE so einen NetworkManager abschalten muss. Wie auch immer man so
>   eine Beschreibung hinkriegen könnte... Die ja idealerweise auch noch
>   platformunabhängig sein sollte.

Moment! Distributions-spezifische Informationen gehören *natürlich* mit
in die Doku. Gerade dann, wenn typische Fallen, Denkfehler, etc.
behandelt werden, ist das ein Zeichen, dass die Doku wirklich *mit* dem
Anwender entwickelt wurde.

Bei FAQs ist es ein Zeichen dafür, dass dort *wirklich* häufig gestellte
Fragen auftauchen, und nicht nur Fragen, die die Autoren gerne gestellt
bekämen. Die meisten FAQs, die ich heutzutage finde, sind keine echten
FAQs, sondern benutzen den Frage-Antwort-Dialog lediglich als
stilistisches Mittel. Was für ein Jammer. Das Vorwort des Subversion-
Buches beschreibt dieses Phänomen ziemlich gut:
    http://svnbook.red-bean.com/nightly/en/svn.foreword.html

| Compiling a true FAQ sheet requires a sustained, organized effort: over
| the lifetime of the software, incoming questions must be tracked,
| responses monitored, and all gathered into a coherent, searchable whole
| that reflects the collective experience of users in the wild. It calls
| for the patient, observant attitude of a field naturalist. No grand
| hypothesizing, no visionary pronouncements hereopen eyes and accurate
| note-taking are what's needed most.

Dieses Prinzip ist auch allgemein auf Dokumentation übertragbar. Den
Anwendern sollte über die Schulter geschaut werden, und typische
Probleme in der Doku behandelt bzw. in der Software verbessert werden.

Gibt es zu viele Distributions-Spefizische Hinweise, dann lagert man
sie eben in extra Seiten aus. Auf jeden Fall sind sie aber wichtig,
genauso wie bestimmte bekannte Hardware-Defekte oder ähnliches. Dabei
kann man sich als Regel merken: Wo hätte ich auf jeden Fall davon lesen
müssen, um nicht in den Schlammassel zu geraten? Und dort trägt man
diese Info hinzu.

In den GNU-Manpages gibt es doch manchmal eine Sektion "LINUX NOTES".
Genauso könnte es "Debian Notes" etc. geben. Außerdem könnte man z.B.
alle "SUSE NOTES"-Kaptel extrahieren und zusammenfassend auf eine Seite
bringen, wenn man wollte. Aber bei den Tools sind sie besser aufgehoben,
weil man diese Info ja erst dann benötigt, wenn man mit einem bestimmten
Tool arbeiten will.

> > 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.
> 
> Es hilft aber auch nicht immer, sich mit Doku totzuschmeissen. Google
> findet extrem viel Doku und ist daher über das Optimum hinaus :)

Nein, Google wirft sie einfach nur zusammen. (Gut, mehr kann man im Web
auch nicht tun). Ich rede jedoch davon, ausgewählte Quellen einzubinden
und zwar regelmäßig ihre aktuelle Version. Kein Wust von irgendwelchen
Foren, in denen zufällig gerade etwas Nonsense gelabert wurde. Kein
überfälliger Mist von alten Versionen, es sei denn, es gibt wirklich
noch keine neuere/bessere.

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

In FreeBSD scheinbar schon.

Dort geht es zwar um Kernel-Design und -Schnittstellen. Aber ein großer
Rahmen für Referenzen, Handbücher, Einführungen und "Wie mach man ...?"
steht vor vergleichbaren Bedingungen.

> > Es fehlen im Moment einige wichtige Mechanismen (z.B. Konvertierung
> > von Manpages, Infopages, etc.), 
> 
> Was fehlt denn hier? Geht in PDF und HTML.

Manpage -> reST gibt's nicht.
Infopage -> reST gibt's nicht.

Und das "Manpage -> HTML" ist auch mehr ein Witz als alles andere, wie
ich bereits an anderer Stelle erläutert habe.

> > 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.
> 
> Ja, Wartung; aber das ist noch viel komplzierter!

Richtig. Viel besser wäre ein Mechanismus, mit dem dies jedes Projekt
für sich machen kann.

Oder mit dem das kleine Projekt diese Arbeit an ein große LDP-artiges
Projekt abtreten kann.

> > 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? 
> 
> Was ist denn überhaupt Projektziel? Ein Index aller Linuxdoku?

Nein, "alle Linuxdoku" will eh keiner haben, wie du bereits begründet
hast. Es geht um die *guten* Dokus, und um eine konsistente Einbindung
und Weiterentwicklung derselben. Entweder durch regelmäßige
Aktualisierung aus den Original-Quellen (wenn Doku vom Projekt selbst
verwaltet), oder durch ständige Verbesserung nach dem Wiki-Prinzip (wenn
Doku vom Linuxdoku-Projekt verwaltet, weil z.B. nicht mehr gepflegt oder
so).

> Oder eine Suchmaschine, die die kompletten Resultate plain, HTML oder PDF
> exportieren kann?

Streich die Suchmaschine. Dann ja. Und zwar alles generiert aus
einheitlichen Quellen. Gepflegt von Freiwilligen, ggf. Eingebunden von
woanders. Ähnlich eine Distri, aber mit hoffentlich weniger Wartungs-
audwand. Daher auch meine Fragen nach geschickten Mechanismen und Ideen.

> Was ist mit Doku, die es so nicht gibt, die also fehlt? Ich glaub, daher
> schreiben viele Projekte viel. Es fehlt was, und man versucht was zu
> verbessern. Das klappt so IMHO aus mehreren Gründen nicht.

Ich verstehe nicht genau, was du damit meinst. Kannst du das bitte
erklären?

> > Warum gibt es keine einheitliche Dokumentation?
> 
> Meiner Meinung nach müsste die Antwort lauten:
> Weil eine gute und einheitliche Dokumentation einfach unmöglich ist.

Meine Güte, mit der Argumentation kannst du auch sofort alle Distris
einstampfen, von SuSE über Debian bis FreeBSD. Und sämtliche weitere
Entwicklungen der Freien Software ebenfalls. Denn nichts davon hat den
Status der Perfektion erreicht.

Formulieren wir die Frage also anders:

Wie kann man dem Ziel einer guten und einheitlichen (Linux-)Dokumentation
möglichst nahe kommen?


Viele Grüße,

    Volker

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