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

[Steffen Dettmer]

* Volker Grabsch wrote on Tue, Dec 26, 2006 at 01:04 +0100:
> 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.

Prima, ich mag ja "inspirierative" threads :)

  Ich rück mal alles unwichtige Gelaber ein. (Das andere Gelaber ist der
  Text ganz links, also der ohne Quotiering lol).

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

Ich glaub, das klingt nach einer prima Regel. Hat man immerhin schon mal
mindestens einen kleinen Anhaltspunkt - über den Packagemanager kriegt
man ja raus, zu welchem Paket ein Binary (oder config file) gehört.

> (mit entsprechenden Tools, die z.B. "PROGRAMM --help" in Manpages
> umwandeln, sodass er eine gute Vorlage hat und nicht alles per Hand
> machen muss)

(na gut, im Detail muss man hier natürlich wissen, was man wann wie tut)

  Es gibt ja leider immer noch Programme, die kein --help können.
  Also, man findet hin- und wieder gar welche, wo man kaum rauskriegt, was
  sie eigentlich tun. Bei X Programmen hat man teils lange Listen mit den
  Standard xlib Parametern wie --geometry und so, aber kaum was zum
  Programm selbst. Bei etlichen Tools ist sowas wie help2man natürlich
  prima - spart die doppelte Pflege (und sorgt [hoffentlich] für gute
  --helps). 

  Ob man die erzeugten man pages dann ändert oder lieber auf keinen Fall
  ändert, damit man die bei der nächsten Version neu erzeugen kann (was
  vermutlich auch wieder nur geht, wenn man ggf. den --help Output
  korrigieren kann, hängt vielleicht vom Einzelfall ab)

> Das heißt, unter Debian kommst du mit:
>     man PROGRAMM
> sehr weit, im Vergleich zu anderen Distributionen.

Warum gibt es dann diese neuen man pages eigentlich nicht auch in
anderen Distributionen? Weil die Pakete unterschiedlichen Umfang haben?
Na ja, würde man sicherlich hinkriegen, wenn man wollen würde.

  Ein klassischer Vorteil von man war, dass man die Ausgaben prima
  drucken konnte. Heute druckt man sowas wohl eh nicht mehr, und jeder
  Drucker kann Grafik und 300+ dpi... Aber man hat ja auch einen
  Postscript-Ausgabe-Modus :)

> Eventuell gibt es
> noch Info-Pages:
>     info PROGRAMM

wobei info ja ein "man page" Fallback macht. Laut GNU sollte info ja
immer Tool Nr. 1 sein, soweit ich mich erinnere (falls man es denn
bedienen kann :)).

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

Das ist bei SuSE auch oft so. Allerdings heisst das ja nicht, dass in
jedem Fall ein Quickstart, INSTALL oder hilfreiches README drin ist. 

  Oft ist die Doku sehr knapp oder man wird von ihr erschlagen (und die
  Meinung, was knapp ist und was nicht ist auch nicht bei allen die
  gleiche). Es ist sowieso imemr schwer, es allen Recht zu machen.
  
  Da wären wir dann auch schon wieder bei der Doku-Diskussions-Punkten
  "Tutorial-Stil" bzw. "Aufgabenorientiertheit" und so, hatten wir ja
  gerade kürzlich.
  
  Zu einem zentralen Doku-Verzeichnis muss
  ich aus RPM-Sicht noch was sagen: verwendet man %doc, sind die RPMs
  nicht mehr relozierbar (man kann sie nicht woanders hin installieren).
  Macht heut anscheinend eh kaum einer, oder? Komisch eigentlich. Man kann
  höchstens /usr/share/doc/PAKETNAME/VERSION/ oder sowas machen.
  Installiert man alles in irgendwas mit "version", kann man endlich auch
  wieder verschiedene Versionen nebeneinander installieren. Das geht mit
  RPM (aber nicht so, wie RPM üblicherweise benutzt wird).
  
  Daher könnte man sowas wie /usr/share/doc/PAKETNAME als symlink zur
  neuesten oder zuletzt installieren /usr/share/doc/PAKETNAME-VERSION oder
  sowas machen, das fänd ich Klasse.

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

Ja, aber wenn man "Regeln" hat, die üblicherweise schon mal helfen, ist
das schon mal was, finde ich!

> 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). SuSE machte dann kurz einen Abstecher zu apt und favoritisiert
  gerade "smart". Ziemlich blöder Name, BTW, find ich. Wenn man danach
  googelt, findet man alles mögliche.  Vielleicht hätte man das tool
  "aspt77" nennen sollen oder so (das gibt bei google null treffer) :-) Na
  ja, versuche man mal was über "THE" mit google zu finden, klappt auch
  nicht wirklich, aber
  
  http://en.wikipedia.org/wiki/THE
  
  geht.

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

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

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

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

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

  Zu Deinen "Plaintext" Beispielen: Wiki-Markup OK. Manpages sind auch
  meiner Meinung nach im Plaintext kaum lesbar. 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...
  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.

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.

  Das ist IMHO ähnlich mit den HTML-Vorteilen: man kann irgendeinen
  Browser nehmen, den man kennt und mag.

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

  Da man mit HTML und CGI ja info, man und sonstwas für komplexe Tools
  bauen kann (bis hin zum Online-banking - und man denke an Web 2.0)
  hinkt der Vergleich plain text vs. HTML/CGI meiner Meinung nach
  ziemlich :)

  HTML selbst (also ohne CGI und Intelligenz) ist auch recht beschränkt;
  HTML mit CGI und Kram ist andererseits kaum portabel, also auch recht
  "beschränkt", wenn man so will. Am Ende braucht man zwei super
  komplexe Tools (Browser Suite mit 512 Plug-Ins und Apache Tomcat J2EE
  Server oder was weiss ich) um einen Text anzuzeigen...

> PDF
> ---
> Hier kommt PDF ins Spiel. 

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

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

  Ja, sowas wie das "HTML zweiter Art" von oben, eine Art Schnittstelle
  zum pdf-viewer. Geht auch daher nur mit Grafik und braucht fett
  Resourcen. Ja, ich weiss dass es modernes Mobiltelefon PDF kann :)
  Trozdem zählt jede Sekunde Antwortzeit, finde ich. Mit Text-tools ist
  oft alles schnell (selbst das man mit seinem rumformatiere und gecache
  ist oft schneller fertig, als ein acroread startet ;)). 

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

  In letzerem Fall würde man sich wohl gar nicht so über die
  Lösungsmöglichkeiten an sich ärgern, sondern mehr darüber, wie sie
  benutzt werden. Beispielsweise, wenn es gar keine man page gibt oder die
  keine Erklärung hat sondern nur Referenz ist, vielleicht weil aus --help
  generiert usw.

Ich glaube, es gibt mehrere Anwendungen von Dokumentation und Bedarf für
mehrere Werkzeuge.

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

  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.

  Weiterhin unterscheidet sich Dokumentation ja in der Zielgruppe
  (Entwickler, Administrator, Benutzer, "Poweruser", "Gelegenheitsnutzer",
  "Quereinsteiger", "Newbie" usw.) und damit im Niveau und Fokus. Auch
  allgemeine und spezielle Dokumentation könnte man unterscheiden. Das
  (also die Doku) lässt sich nichtmal baumartig einordnen...

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

Gibt es ein Dokusystem für Sourcecode-Dokumentation, was Java, Python,
C, C++ und Perl Doku nach plaintext/man, LaTeX/PDF kohärent erzeugen
kann?

  Ich kenn nur Doxygen, das geht relativ gut für C++ und Java, kann HTML
  und PDF (und mehr).

  In der Praxis hab ich aber ein Problem damit. Ich habe ähnliche APIs
  in C++ und Java. Einerseits möchte ich die Doku nicht hin- und
  herkopieren und redundant pflegen, andererseits ist sie auch nicht
  genau gleich usw. Doxygen kennt \copydoc, aber auch das hat Nachteile
  (der Javaentwickler muss C++ Sourcen ändern oder umgekehrt etc).

  Das Problem liegt wohl weniger im Tool als wohl eher im Problem selbst
  (d.h., ich glaube, das Problem ist vielleicht gar nicht elegant
  lösbar).

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

Dann müsste natürlich erst reST überall gehen, bevor es "Standard"
werden kann - und überall geht :) 

  Sonst hat man nur Plaintext... Gut, dieser ist besser als ne man page
  ohne man - aber keine Konkurenz zu HTML. Daher sollt man Doku wohl als
  HTML UND PDF UND Plaintext in seine Binärinstallation oder Package (RPM,
  ...) packen - wenn möglich, aus einer Quelle erzeugt.

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

  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.

  Online ist man vielleicht nicht usw.

  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.

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

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

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

  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.

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

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

Am Ende ist auch "Wartung" ein Riesenproblem. 

  In den Softwareprojekten wird (mind. solche) Doku-Wartung ja i.d.R.
  nicht eingeplant und findet daher manchmal (oft) überhaupt nicht
  statt. Das sieht man heute auch gut im Internet; man muss schon auf
  die Version achten. Zu älterer Software findet man kaum noch was.
  Heute kann man vermutlich nichtmal mehr ne SuSE 7.3 downloaden...

  Die Doku von damals ist sicherlich grösstenteils veraltet im Bezug auf
  aktuelle Programme. ls und so werden noch sehr ähnlich sein, aber bei
  KDE ist wohl kaum ein Stein auf dem alten geblieben. Eigentlich nur
  ein Zeichen dafür, dass diese Software noch nicht reif ist.

  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 (endet dann in einer Auflistung der
  GUI Elemente. Dann steht da "Bei `Modus' wählen Sie den Modus aus."
  usw.). 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...

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

  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.

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

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

Na ja, geht gar nicht perfekt. 

  API Docs haben auch schon zwei Hauptzielgruppen: Benutzer (mit
  Unterzielgruppen) und Libentwickler.  Letzere möchten auch Infos, wie
  die Funktion heute gerade zufällig arbeitet, was die Benutzer gerade
  nicht wissen sollen.

  "Perfekte Beispiele" zu finden, geht auch nicht - irgendeinem fehlt
  "seins" ja immer.

  Didaktisch gut heisst oft, die API aus praktischer Benutzungssicht zu
  beschreiben. Das ist aber ungünstig als Referenz... 

  usw.

> Der normale Programmierer, wie ich, ist schon froh, wenn jede Funktion
> einen nicht-trivialen Docstring besitzt. 

pro-Funktion-Dokumentation ist meiner Meinung nach als API-Dokumentation
absolut unzureichend.

  Es muss auch erklärt werden, warum man welche Funktion nu wann aufruft
  oder nicht usw. Das an die Funktionen zu schreiben wird redundant und
  ach, geht überhaupt nicht.

> Also kommt ein API-Doc-Generator her. 

Ein Tool wie JavaDoc oder Doxygen löst IMHO ein anderes Problem. Nicht
das der knappen Doku, sondern es löst das Problem der Wartbarkeit (ein
bisschen).

> Es wäre zu schön, wenn die Tools nicht blind nach HTML konvertieren
> würden, sondern erstmal nach reST.  

Wieso dass denn, die JavaDoc/Doxygen-Kommentare kann man ja auch im
plain text lesen (was man als Entwickler ja oft auch macht). Also wozu
nu hier noch reST?

  Beruflich hab ich ne Lib mit irgendwas um die 300 Seiten PDF.
  Praktisch eigentlich nur als HTML benutzbar. Wüsste jetzt nicht, warum
  man das noch als reST wollen würde.

> Es ist ja schön, dass EpyDoc dem JavaDoc nacheifern will, aber man
> sollte nur die guten Ideen kopieren.

Ich finde JavaDoc (im Vergleich zu Doxygen) nicht so toll; aber alles
steht und fällt damit, wie man es benutzt.

  Die Frames-Ansicht und überhaupt eine "All Classes" liste ist blöd.
  Dann mit dem Browser suchen... Such mal "table" oder so :) Die JavaDoc
  ist wirklich viel besser geworden, inzwischen (Java 5) gibts etliches an
  "Class" Doku. Da wird auch öfter mal "rausgelinkt" (was nicht schlecht
  ist). Aber gerade der "Ganzheitliche" Blick fehlt. Beispielsweise findet
  man nicht herraus, wie man mit java.util.logging und dem built-in config
  file support über -Dlogging.properties (oder sowas, finds gerade nicht)
  zwei Logfiles einstellt (es geht nicht - warum auch immer das während
  der Implementierung keinem aufgefallen ist!).

  Zu etlichen Libs gibs seitenlange javadocs, aber die helfen einem
  nicht so wirklich. Entweder versteht man sie nicht, weil man sich noch
  nicht genug auskennt, oder man kennt sich aus und sie hilft einem
  nicht weiter :-)

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

Sozusagen README als Einführung?

Doxygen kennt hierzu "mainpage" und "pages". Find ich Klasse.

  Und man kann "Module" frei definieren (meine Packagestruktur muss ja
  nicht zu der Struktur meiner Doku passen!)

> 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* würde Mitarbeit anregen.

  (Foren regen auch zur Mitarbeit an - mit dem Ergebnis, dass google
   kaum noch benutzbar ist...) 

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

> Es erscheint mir absurd, hier die selben Erwartungen zu hegen wie bei
> der Wikipedia: Diese ist einzigartig. 

Naja, zu etlichen Themen gibt es andere Wikis; gerade im
"Computerumfeld" (Software-Entwickung z.B.)

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

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

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

(Falls es das denn überhaupt möglich ist)

  Vielleicht fehlt auch die natürliche Zahl die ein ganzahliges
  Vielfaches von "pi" ist... :-)

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

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

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

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

> Es fehlen im Moment einige wichtige Mechanismen (z.B. Konvertierung
> von Manpages, Infopages, etc.), 

Was fehlt denn hier? Geht in PDF und HTML.

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

> 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? Oder eine
Suchmaschine, die die kompletten Resultate plain, HTML oder PDF
exportieren kann?

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.

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

Danke, war sehr interessant. Die ursprüngliche Frage war ja

> Warum gibt es keine einheitliche Dokumentation?

Meiner Meinung nach müsste die Antwort lauten:

Weil eine gute und einheitliche Dokumentation einfach unmöglich ist.

oki,

Steffen

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