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

[Steffen Dettmer]

* Volker Grabsch wrote on Sun, Dec 31, 2006 at 09:18 +0100:
> > 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

Nee, "view"! :-)

> > 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.

OK! Ja klar, die sollen natürlich zusammenpassen und "insgesammt gut"
und "schön" sein.

> Weiterhin kannst du "Lernen" und "Nachschlagen" zusammenfassen. 

Finde ich nicht. Bei Lernen möchte ich von "einfach" nach "schwierig"
oder von "oft wichtig" zu "selten wichtig" sortierte Informationen. Bei
Nachschlagen hingegen z.B. alphabetisch sortierte. Bei Lernen möchte ich
nicht durch jede noch so exotische Ausnahme abgelenkt werden, die
spzifiziert ist. Bei Nachschlagen hingegen muss jede Ausnahme erklärt
sein.

Finde beides schon sehr unterschiedlich!

"Linux nach manpages zu lernen", fände ich z.B. schlich falsch.

> 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.

(Weiss nicht, ob die beliebte find|xargs Kombination überhaupt in
irgendeiner manpage steht...)

> >   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?

Nee, leider nicht wirklich. Das Runlevel-Konzept von Selflinux war eine
Idee (ist meines Wissens nach aber leider nie probiert worden).

Beim Doku schreiben ist oft nicht klar, dass die Doku fünfmal so lange
dauern "sollte", wie die reine Textschreibzeit. Dazu kommt ggf. Freigabe
und dann Wartung usw. Kann natürlich am Ende endloss sein ;)

Aber Dokumentieren heisst ja nicht nur "mal was schreiben und
vergessen". Aber mehr oder weniger passiert das. Ich nehme mich da
selbst nicht aus. Ich hab für SelfLinux geschrieben (also, eigentlich
hab ich geschrieben für irgendwen wie z.B. SelfLinux), bin dann da raus
und habs nicht weiter gepflegt. Das Feedback war sowieso ein Witz
(handvoll Mails im Jahr; den drei Leuten kann ich das auch per
R-Gespräch erklären - selbst wenn ich zahle kommt mich das billiger...).

Na ja, bei SelfLinux fand ich die (alten) Ideen eigentlich gut.
Schreiben als plain-Text (damit "allgemeingültig"), Tutorial-Charakter,
Runlevel-Konzept. Natürlich Index und Inhalt etc. Prima Ansätze. Mit
dem Ergebnis war ich persönlich dann jetzt aber nicht soooo zufrieden
(Vollständigkeit, Wartung, ...). Da haben sie viele Leute viel Mühe
gegeben. Daraus folgt vermutlich, dass das Thema sehr komplex ist.

> 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.

Na, ich find das gut. Wenn mail schwierig zu benutzen wäre, also
grössere Einstiegshürde, würdes es VIEL weniger nutzen und es würde kaum
Spam geben. Wenn die Linux-Doku nicht so verdammt gut wäre, hätten keine
Windows-User das Linux in ein Windows-Clone kaputtgewünscht usw.

Ich hab da auch noch den Vorschlag vom kompliziert zu bedienenden,
GUI-freien Kommunikationstool. Dem "Netz" dahinter sind GUIs per Lizenz
absolut verboten, nur text modus CLI ist erlaubt. Könnte man als IRC
Nachfolger sehen. IRC war ja benutzbar bis 1996 oder so, bis "alle
kamen". So ein krepliges text modus Tool würde die Masse nicht
interessieren und könnte daher angenehm zu nutzen sein. 

:)

> > > 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).

Na gut, wenn ich HTML oder PDF reinpacke, ist ja wieder egal, wie ich
das erzeuge. Da kann ich die PDFs dann auch aus MS Word Dokumenten
erzeugen oder so.

> Das Wiki war für die Projektseite gedacht. So kann dann jeder etwas
> daran ändern, wenn er online die Doku durchgeht. 

Warum nicht einfach SCM Tool und Editor? Also CVS + vim oder SVN oder
so?

Wikis sind IMHO zum Teil einfach ein "Sandboxersatz" (ohne Sandkasten,
ich muss ja speichern, um es zu sehen... nee... na fast... egal.). Hat
natürlich ein paar Vorteile (schnelle Links, Suche, ...). Aber das nu
als Werkzeug statt SCM Tool... ich weiss nicht...

> >   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?

Das es gebraucht wird schon; ich meine ja, gibts jetzt vielleicht noch
nicht (wirklich).

> >   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.

Das funktioniert halt nicht immer. Das Wiki ist sicherlich nicht so gut
sauber "freigebbar". Kann ich es taggen und branchen (für verschiedene
Lib-Branches z.B.)? Kann ich es wirklich ausdrucken? PDF geht einfach in
der Praxis. Aber wenn man ein Tool braucht... Vielleicht geht die neue
Version mit den alten Seiten nicht oder weiss ich was.

Ich finde, ein Wiki ist ein Wiki und kein Handbuch-Ersatz. Es ist gut,
um schnell Infos festzuhalen (Zettelkasten) und für erste
Strukturierungen. Für eine durchdachte, hochentwickelte Doku aber nur
sehr bedingt geeignet.


> > 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?

So war die Idee des "Runlevel Konzeptes" in SelfLinux (in etwa). Die
Idee war, Textbausteine sind je Level da oder nicht mit der Erwartung,
dass man kaum Redundanz braucht. So nach dem Motto (1: leicht, 4:
experte, 5: nerd):

Level    	Baustein
1 2 3 4 5
X X X X X       Copyright
X X - - -       Einleitung Newbie
- X X X -       Einleitung Experte
- - - - X       gr33tinx an die kewle crew

usw. 

Anforderung ist ein flüssig lesbares Dokument in jedem Runlevel (also
so, als ob es keine solchen gäbe).

Hat bei trivialen Sachen geklappt, glaub ich. Bei anderen nicht. Da
werden Wörter verwendet, die aber nur im höheren Runlevel definiert
wurden, muss man für keineren umformulieren. Dadurch passt der Satzbezug
im Folgenden nicht mehr, muss man auch umschreiben. In niedrigeren
Runleveln möchte man natürlich auf höhere verweisen können, aber muss am
Ende noch sinnvoller Text bei rauskommen (aber hier gabs wohl mehr
praktische Probleme mit XML Geschichten). Eventuell ist die Reihenfolge
anders (Experten kriegen kurze Compile/Install-Prozedur; die springen eh
da rüber, wenn sie ein RPM haben aber erwarten das einfach am Anfang.
Dann Konfiguration. Für Newbies lieber erstmal Einführung worum es geht,
dann Beispiele, dann Konfiguration, weil hier angenommen wird, dass die
verwendete Distribution das benutzbar mitbringt und der Einsteiger
schnell mal was machen will und auch schnell ein Erfolgserlebnis will).

Möglicherweise sind die Beispiele anders (Newbies eher
Multimedia oder so, Experten was bekanntes technisches oder so).
Natürlich müssen die Elemente erklärt werden (also unterschiedlicher
Text).

Interessant ist die Frage, ob der Stil unterschiedlich sein kann / sein
sollte. Für Newbies sollte man "Witze" vermeiden, die zu
Missverständnissen führen könnten. Für Experten sind solche "Witze" aber
vielleicht die ideale Auflockerung (sie wissen, dass das CD ROM kein
Kaffeetassenhalter ist). Für Newbies lieber Analogien zu Sachen aus der
natürlichen Welt, für Experten vielleicht von Standardtools (ein
Linux-Experte wird "ls" zumindestens kennen. Für einen Experten kann man
schreiben "Tool XYZ macht für CATALOG in etwa das, was ls für
Verzeichnisse macht" oder sowas. Ein Newbie würde genervt sein, weil er
dem ls link folgen soll und am Ende nicht versteht, wie das nu
zusammenhängt. Wünschen Experten einen eher knappen Ton?

Vielleicht sind diese Eigenschaften aber auch weitere "Dimensionen".
Also newbie_brief newbie_poetic expert_brief expert_poetic usw statt
Runleveln?

Na, und so weiter.

Am Ende war selbst mit diversen pragmatischen Vereinfachungen zu
erwarten, dass es kaum gemeinsam nutzbare Textbausteine gibt (es sei
denn, man hätte "viele" Runlevels, aber das hat auch nicht den Wert).

Man schreibt also einfach 5 verschiedene Texte, das spart Arbeit (!).

Nun lässt sich sowas natürlich schlecht verkaufen (klingt einfach nicht
sexy), ausserdem "verrät" es, wieviel Arbeit es wirklich macht etc.

Die Wartung ist ebenfalls deutlich aufwändiger (also wieder wie für 5
Texte).

Aber vielleicht war entweder der Ansatz falsch oder die Umsetzungsideen;
vielleicht gibts ja ne bessere Idee. Vielleicht hat irgendwann mal
jemand eine, die alle überzeugt und geht; das wäre mal was.

> >   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.

Ja, wie oben geschrieben: entweder gibt es keinen solchen (brauchbaren)
oder wir haben ihn nur nicht gefunden.
 
> >   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.

Ja, aber zum einen es gibt verschiedene Arten von Redundanz. Zum anderen
brauchen Menschen Redundanz. Das ist wichtig und darf nicht vergessen
werden.

> > 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.

Ja, schönes Beispiel, genau so. Hat man bei GUIs oft, finde ich. "Klicken
sie Schliessen zum schliessen oder brechen sie mit Abbrechen ab.".
"Öffnen Sie ihr Dokument mit Öffnen. Im Feld Dateiname geben sie den
Dateinamen ein". usw.

> 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.

"Im Feld Dateiname geben sie den Dateinamen ein" ist selbst als Tooltip
blöd. Aber in einem Handbuch IMHO einfach nur fehlplaziert. Das ist "ich
dokumentiere, weil ich muss".

> 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.

Ja, genau, Screenshots vom Öffnen-Dialog oder so, genau :)

> >   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. 

Ja, aber Realität.

> > 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 hab mit LaTeX z.B. keine schönen Tabellen hinbekommen (kannte auch
keinen LaTeX-Guru). LaTeX ist ein Satz-System, kein automatischer
Formatierer. LaTeX nehm ich, wenn ich ein schönes Dokument drucken will.
Passt ein Abschnitt nicht, formuliere ich ihn notfalls um, damit er
passt oder mein Fachbegriff nicht ungünstig getrennt wird oder meine
Tabelle past usw.

> >   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.

na gut, vielleicht kenn ich das Tool, was das kann nur einfach nicht.

Doxygen ist es jedenfalls nicht. Da sind oft massig Details, die ich in
den PDFs lieber anders hätte (geht aber halt nicht, weil automatisch
erzeugt). Na ja.

> >   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.

(Ja komisch, weiss auch nicht mehr genau)

> 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.

In LaTeX muss man das Verzeichnis einfügen, macht man meist vorn. Das
geht nicht automatisch. Könnte natürlich das reST->LaTeX Tool
machen, klar. Aber macht es dass so, wie für *das* Dokument sinnvoll?
Ich verwende (in MS Word) verschiedene Inhaltsverzeichnisse (die
man nicht mehr durck klicken einfügen kann, sondern mit Feldbefehlen
definieren muss). Das hängt vom Dokument ab. Manchmal will ich Ebene 4,
oft nicht. Will ich sie, will ich sie ohne Seitenzahlen (bisher
jedenfalls). Na ja, usw.

> 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).

Im Fehlerfall sind mir einfache klare aber lieber. Ein h1 in HTML ist
eindeutig und klar. Wikis oder so interpretieren Sachen aber manchmal
falsch (i.d.R. natürlich, weil man was falsch gemacht hat), ohne das man
das sofort merkt, manchmal findet man das auch nicht gleich.

> > 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.

Ahh, OK, das klingt cool. Gibt's sowas?

Ist im Detail komplexer, weil jeder ein Wiki ändern können soll aber
nicht (unbedingt) jeder die Sourcen.

> Ü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!

ja ich weiss, Subversion kann HTTP und SSL. Wer's braucht... CVS geht
über SSH, viel besser *find ich*. Ich find CVS und SVN sind sich recht
ähnlich. Leider hat CVS paar komische Bugs. Mit SVN hab ich keine
Erfahrungen. Ich hab da nur ein einziges Repo. Aber das mit derm mergen
und so ist IMHO alles nicht besser als bei CVS. Ob SVN problemlos über
mehrere Repos und hoher automation funktioniert, muss sich aber wohl
auch erst herrausstellen. Ob dann checkin noch atomar ist (soferns das
überhaupt ist!), wage ich z.B.  zu bezweifeln.

> 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, 

Versteh ich nicht. Was ist denn da gross anders? Branches zu verwenden
und zu mergen ist im SVN für mich schwieriger. Ich kann lahme
visualisierungstools nehmen, ok, mag sein. Aber ich kann nich taggen,
wenn nicht eingecheckt ist, ein tag ist ein branch, was ich aber
vielleicht nicht will, wenn ich mergen will, muss ich repository nummern
nehmen, ARGHHH; keine Symbole, schlimmer als CVS. Die Nummern *können*
gar nicht repository-übergreifend funktionieren, also kann ich nicht
repo-übergreifend mergen, oder? Na ja usw.

> Darcs und Mercurial umso mehr.

Darcs ist Changeset-basiert, ja? Das klingt mächtiger als CVS, hab ich
aber noch nicht benutzen dürfen, sowas. Na ja, ich glaub, hier war das
Problem, dass es lahm ist?

Mal sehen, vielleicht ist SVN vs. <anderen> sowas wie mySQL vs.
PostgreSQL. Ersteres ist bekannt und gehypt aber nicht unbedingt besser.
In vielen Teilen sogar deutlich schlechter. Wer weiss. Die Artikel, die
ich über SVN gelesen hab, waren IMHO jedenfalls nicht dolle. SVN kann
HTTP, na super. Da kann man nur ablachen. CVS kann *alles*, was auf
rsh/ssh oder so zurückzuführen geht. Die meisten Bugs von CVS können die
Leute, die SVN in den Himmel loben, nie gehabt haben, weil die nur
einzelne mini repos haben und nicht noch 9 Jahre alte Stände bauen
können müssen etc.

SVN ist nett, scheint teils schneller etc., aber meiner Meinung nach ist
es auch nur ein CVS mit anderem Lack...

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

Darauf wollte ich auch nicht hinaus. Im Allgemeinen ist aber Quantität
nicht alles. Oder wie PostgreSQL mal gesagt hat: wir brauchen nicht
viele Entwickler mit wenig Zeit, sondern wenige mit viel Zeit.

> >   (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.

Bis das denn verschwindet...

> 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.

Bei SelfLinux scheiterte das z.B. daran, dass man SF CVS gegen ein
anders strukturiertes SVN Repo getauscht hat, die URLs geändert wurden
(.de nach .org und keine "Entwicklerversion" mehr, sieht man den Seiten
heute noch an) usw.

Da stehste dann da mit Deinem Link... Und wenn Du Pech hast, kannste das
nicht mehr *da* ändern (ich kann z.B. im Falle von SelfLinux meine
Dokumente im SelfLinux SVN nicht ändern). Das ist dann schnell
ärgerlich. z.B., wenn Dir ein Fehler jeden Monat gemailt wird.

> > > 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.

Ja, ich mein auf dem Gebiet. Ein News-Anfänger sollte keinen inn Artikel
schreiben, finde ich. Das geht schnell schief. Überhaupt sollten
Anfänger auch kein inn nehmen. ;)

> 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.

Ja klar kann er helfen. Fragt sich, ob er wirklich herrausgefunden hat,
wie es richtig ist (oder nur wie es zufällig für ihn funktioniert).

Bei Software schicken die Leute i.d.R. auch Patches und der Maintainter
prüft, ob die reinkommen, deren Idee oder gar nichts reinkommt.

Sollte man bei Doku genauso machen. BTW, Doku *sind* Software.

> > > 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?

Weiss nicht. Theoretisch könnte ich mir das sogar vorstellen. Praktisch
hatte ich sowas noch nie. Praktisch funktionierte immer ein Anruf am
Besten. Bei OpenSource könnte das ja ein VoIP Call sein oder eine IRC
Sitzung. Vielleicht auch ein Wiki, wer weiss. Diskussionseiten sind ja
prima. Kommt natürlich auch auf den Maintainer an. Wichtig ist, dass sie
Ausnahmemeinungen von denen, die schreibwütig sind, nicht allein
durchsetzen (wenn 3 von 1000 der Meinung A sind und alle anderen der
Meinung B, aber genau die 3 eine Bewertung schreiben, könnte man ja
denken, alle sind Meinung A!). Na ja, im Detail komplex, klar.

> > 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.

Das war ein Riesenproblem bei SelfLinux. Höhrere Ebenen (KDE,
Desktopkram) ging einfach nicht mehr. SelfLinux sollte nicht
Distri-Spezifisch sein. Autoren können sowas nicht bie "allen" Distros
testen oder wissen. usw. Also kann man das entweder vermeiden (sprich:
nicht in die Doku aufnehmen) wie SelfLinux das meistens macht (was IMHO
auch nicht sinnvoll ist, weil es so in "jeder" Distro falsch ist) oder
hat ein anderes Problem.

> 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.

na klar, wie ja bei der (restlichen) Software auch.

> 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. 

Ja, schon klar. Aber um WLAN zu beschreiben, müsste man "alle"
Distributionen installiert haben. SuSE hat den NetworkManager, RedHat
hat weiss ich was, FC das nächste, Debian machts über dpgk-reconfigure,
ach keine Ahnung. Wer soll sowas schreiben können? Ist ein ganz
praktisches Problem!

Gute Doku pflegt halt das Projekt mit. Also wenn jemand einen
NetworkManager erfindet, passt er die WLAN Doku an. Geht bei Linux auch
nicht wirklich, weil es ja jede denkbare Doku in 10 verschiedenen Formen
gibt :)

> > 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.

Das war damals bei SelfLinux auch so eine Diskussion. Viele waren
dagegen, lieber verlinken. Oder meinst Du das mit "einbinden"? Wie auch
immer, es macht Wartungsaufwand etc.

> > > 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.

Du kritisierst man und info und kommst mit reST als Gegenvorschlag. Dann
ist es doch ein Nachteil von reST, wenns das nicht gibt, nicht von man!

Sonst könnte man ja sagen, steffDox ist besser, aber man ist Mist,
weil es nicht nach steffDox exportieren kann :)

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

mm... Was ich ergooglet hatte (falls mal), hat mir meistens gefallen.

> > > 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. 

(ja gut, natürlich nicht "alle", meinte sowas wie "die beste zu jedem
Thema"  oder so)

> 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).

Ich fürchte, man würde nur feststellen, dass man viel überarbeiten
müsste, würde damit anfangen und dann nach 10 Texten hängenbleiben, wie
schon so oft ;)

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

(iss dann aber ein komischer Satz... ;))

> 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.

Nette Theorie, aber halte ich leider für kaum möglich...

> > 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?

Na ja, z.B. gibt es vielleicht "Linux auf R30" und "Linux auf R40"
(Laptops von IBM), aber nicht "Linux auf R32", also möchte man "Linux
auf R-Series" machen, muss ja, oder? Aber wie bzw. wer?

Technisch/logisch ist klar, dass man das *muss*, aber man kann nicht.
Geht schon beim Testen los. Man hat entweder einen R30 oder einen R32,
aber wer hat "alle"? Wer kann das warten? Wenn ein neues R1000 kommt
oder so? Und vor allem: wenn eine neue Distro-Version kommt?

Da sind wir wieder beim Wartungsproblem. Ein Jahr Linuxentwicklung
reicht heute wohl, dass für den Einsteiger nichts mehr gleich ist (merkt
dieser natürlich nicht, klar). Jedenfalls zu schnelllebig, um gut
dokumentiert werden zu können. Na, anders Thema.

> > 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?

Ich glaub, Du hast falsch verstanden. Ich meinte, die Frage ist falsch.

Warum einheitlich? Warum nicht ein interaktives Tutorial, eine HTML und
"Lexikon" Referenz als PDF-Buch, verschiedene andere Arten von Hand-,
Einsteiger- und Umsteigerbüchern. APIs bleiben Doxygen, JavaDox, epiDoc
oder was auch immer, weil die Tools dafür halt gut sind.

Ich meine also, warum nicht ein Tool da nehmen, wo es stark ist und in
anderen Fällen ein anderes? Passt doch auch gut zum Unixgedanken :)

oki,

Steffen

-- 
Dieses Schreiben wurde maschinell erstellt,
es trägt daher weder Unterschrift noch Siegel.