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

[Volker Grabsch]

On Mon, Jan 01, 2007 at 10:36:36PM +0100, Steffen Dettmer wrote:
> > 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...)

siehe "man xargs", Abschnitt "EXAMPLES".

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

Ich denke, genau diese Art von Abgrenzung ist nicht zu empfehlen. Die
Hacker-Gemeinde hat sich schon immer gern im Newbies gekümmert und über
DAUs geschimpft. Aber wo liegt die Grenze? Sind es wirklich nur die
Masochisten unter den Anfängern, aus denen gute Newbies statt DAUs
werden? Hat nicht jeder mal mit Klickibunti angefangen, bis es ihm
zu viel wurde?

Im Gegenteil: Wären die graphischen IRC-Werkzeuge von den "Konsolen-
Freaks" entwickelt worden, wäre in diese viel mehr Standardkonformität
hinein gekommen. Das gilt umso mehr für Newsreader.

Stattdessen werden die GUIs verpönt, aber der Bedarf ist trotzdem da.
Ist doch klar, dass dann gerade diejenigen die GUI-Clients programmieren,
von denen man es nicht will. Und dass dort viel mehr fehlgeleitetes
Design hinein kommt, als hätte es ein Experte entworfen. Aber selbst
schuld.

Wenn sich die Fähigen dafür zu fein sind, wird es eben von Unfähigen
gemacht.

Ein graphischer Port von slrn, mit Buttons und Menüs zusätzlich zu
den Tasten-Befehlen, optisch ansprechend gestaltet, portabel
geschrieben, das wäre sicher der Renner geworden! Der hätte kein
Kammquoting gemacht, bei Zeilenlängen über 80 Zeichen gewarnt, und so
weiter. FAQs vielleicht gesondert dargestellt, damit sie nicht ignoriert
werden. Anfänger wären vom Programm in die richtige Richtung "erzogen"
worden.

Das AOL/Outlook-Phänomen wäre im Keim erstickt. Man hätte immer
sagen können: "Nehmt xslrn (oder winslrn), das ist viel einfacher zu
bedienen und ihr fallt hier nicht unangenehm auf." Stattdessen lässt
man diese Ecke wuchern, und Ahnungslose und Geldschneider (nicht selten
in einer Person) ihr Unwesen mit den Anfängern treiben.


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

anfängerfreundlichkeit

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

Nicht "statt" sondern "zusätzlich zum".

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

Die Wiki-Software, richtig. Deshalb ja auch SCM+Editor.

Aber diese "durchdachte, hochentwickelte Doku" kann man doch wiederum
als Wiki zur Verfügung stellen. Was spricht denn dagegen? Diese ist doch
nun, dank ihrer durchdachten strukturierung, noch viel leichter
anzupassen, zu korrigieren und zu ergänzen.

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

Es gibt SubWiki, das intern Subversion verwendet. Weiß aber nicht, wie
gut das mittlerweile ist. Die guten und bekannten Wikis (MediaWiki,
DokuWiki) kochen da leider ihr eigenes Süppchen. MediaWiki mit MySQL,
DokuWiki mit RCS.

Unterstützung mehrerer Backends und mehrere Wiki-Formate, also Trennung
von Speicherung/Versionierung, HTML/PDF-Generierung und Benutzerschnitt-
stelle, fordere ich schon lange. Ein Wiki sollte ein Webinterface für
versionierte Texte sein, und die Details an andere Tools abgeben.

Bei riesigen Projekten wie Wikipedia geht das natürlich nicht, da werden
viele Zusatzfeatures gebraucht. Aber für Dokumentations-Wikis von
Projektseiten wäre das genau das richtige.

Diese und weitere Gedanken habe ich mal zusammengefasst:
    https://dev.njh6.de/wiki/index.php?title=Wikidok

Einen sehr interessanten Thread zu dem Thema gab's hier auf der Liste
auch mal.


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

Die naheliegende Lösung ist, dass das Wiki nur auf ein bestimmtes
Verzeichnis im Repository zugreift. (doc/ oder doc/community/ oder was
immer man möchte)


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

Lamport empfielt in seinem Buch, dass man in Tabellen möglichst auf
Linien verzichten sollte, das macht sie übersichtlicher. Es widerspricht
allem, was ich gewohnt bin, aber nachdem ich schon ein paar mal damit
herumgehadert habe, muss ich sagen: Der Mann hat recht. Man ist viel zu
leicht versucht, Doppel-Linien, dickere Linien etc. reinzubringen,
obwohl man die dünnen einfach weglassen sollte.

Das ist also eher ein Feature, kein Bug.

Lesehilfen (jede zweite Zeile grau hinterlegt oder so) gibt's wohl auch
für LaTeX, da kenn ich mich aber nicht so aus.

> LaTeX ist ein Satz-System, kein automatischer Formatierer.

LaTeX ist beides. Um sehr, sehr viele typische Textsatz-Probleme kümmert
es sich automatisch.

> LaTeX nehm ich, wenn ich ein schönes Dokument drucken will.
> Passt ein Abschnitt nicht, formuliere ich ihn notfalls um, damit er
> passt

Mach ich genauso. Aber erst ganz zum Schluss, kurz vor dem Druck. So
empfielt es auch Lamport. Das meiste zuvor kann man aber auch
automatisch erledigen lassen.

> oder mein Fachbegriff nicht ungünstig getrennt wird

Du kannst LaTeX Tenn-Hinweise geben:

    LangesWort\-HierTrennen

Dann trennt LaTeX dort, wenn es sich anbietet, ansonsten lässt es das
Wort ganz.

> oder meine Tabelle past usw.

Ja, mach ich auch. Aber meistens ist das Pedantismus und nicht wirklich
nötig, weil auch ungünstige Tabellen von LaTeX immer noch so gut wie
möglich gesetzt werden.

Ich denke, das Problem liegt eher darin, dass die meisten Tools einen
LaTeX-Code erzeugen, der für Menschen nicht mehr lesbar ist. Das ist
natürlich schade. Wenn meine Applikationen LaTeX erzeugen, bemühe ich
mich, dass genau das nicht passiert. Dann mache ich vor dem Druck letzte
optische Korrekturen, und das war's dann.

Macht sich zimelich gut.

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

Das ist natürlich doof.

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

SVN geht auch über SSH. Mercurial übrigens auch.

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

Richtig. Hast du höhere Ansprüche, nimm Mercurial.

> Ob SVN problemlos über
> mehrere Repos und hoher automation funktioniert, muss sich aber wohl
> auch erst herrausstellen.

SVN ist schon jahrelang im Betrieb. Ich denke, dessen Stabilität und
Eignung zweifelt niemand mehr an.

> Ob dann checkin noch atomar ist (soferns das
> überhaupt ist!), wage ich z.B.  zu bezweifeln.

Soweit ich weiß, ja. Woher nimmst du deine Zweifel? Die Beta-Phase hat
SVN längst überwunden. Mercurial, Darcs und GIT übrigens auch.

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

All das machen Mercurial & Co. natürlich 100x besser, keine Frage. Schau
dir diese mal an.

> keine Symbole, schlimmer als CVS.

Geht in Subversion auch, man muss nur bestimmte Properties setzen. Ich
finde es gut, dass man solche Features erst aktivieren muss, statt sich
zu wundern, wieso das SCM meine Quellen manipuliert. Ist sicher auch
geschmackssache, aber alles konfigurierbar.

In Mercurial z.B. sind Keywords schon nerviger (aber möglich). Habe das
aber zum Glück noch nie gebraucht. Wenn man seine Quellen nicht gerade per
E-Mail weitergibt und wieder einsammelt: Wozu braucht man dann die
Keyword-Ersetzung?

> Die Nummern *können*
> gar nicht repository-übergreifend funktionieren, also kann ich nicht
> repo-übergreifend mergen, oder? Na ja usw.

In Subversion kannst du mehrere Projekte in einem Repository haben,
und dann geht das.

Mercurial & Co. machen das aber schon vom Konzept her besser.

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

Darcs ja. Mercurial und GIT nicht. Die sind hochoptimiert. CVS und SVN
sind dagegen lahm.

> Mal sehen, vielleicht ist SVN vs. <anderen> sowas wie mySQL vs.
> PostgreSQL.

Nützt nichts. Schau dir mal die technischen Beschreibungen zu Mercurial
und/oder GIT an. Die Machen Es Richtig.[tm]

Ein zusätzlicher SQL-Layer brächte dort keine Vorteile, und unnötige.
Einschränkungen. (Man würde ja doch wieder nur einen Haufen BLOBs
abspeichern)

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

Da ist was dran. Und ich mag PostgreSQL übrigens auch lieber. :-)

[Dokus für Anfänger]
> Bei OpenSource könnte das ja ein VoIP Call sein oder eine IRC
> Sitzung.

Stimmt. Auch eine gute Idee. Ich hab schon von Projekten gehört, die das
machen.

> Vielleicht auch ein Wiki, wer weiss.

Hat den Vorteil, dass es nachhaltiger ist. Ein aufgezeichnetes Telefonat
(oder viele davon) würde wahrscheinlich wieder in eine Müllhalde ausarten,
genau wie die Foren.

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

Ganz einfach: Nicht einer alles, sondern jeder ein bisschen. Diese
extra Kapitel pro Distri sollten am besten von jemanden geschrieben
werden, der diese Distri auch aktiv benutzt. Oder die Hinweise stammen
von einem Anfänger, der damit Probleme hatte.

Ich bin ohnehin davon ausgegangen, dass man ein Doku-Projekt nicht
Manpage für Manpage auf einzelne Leute aufteilen kann. Vielleicht kann
man Verantworlichkeiten auf ganze Manpages festlegen, aber gerade "Tipps
& Tricks & Ausrufezeichen" kommen aus verschiedenen Richtungen. Das
liegt in der Natur der Sache.

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

Die FreeBSD-Web-Manpages sehen grauenvoll aus. Siehe anderer Thread.
Mittlerweile habe ich aber auch schon gutaussehende Manpage-Exporte
nach HTML gesehen. Weiß aber leider nicht, was mit welchen Tools gemacht
wurde.

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

In dem Fall: Ja, ein Index wäre ein Anfang. Konsistente Einbindung aber
aber wäre besser. Der Index kann sich in diese Richtung natürlich
mausern. Vielleicht wäre das sogar ein besserer Ansatz. Dann hätte man
das Schreiben von der Zusammenstellung weitestgehend getrennt.

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

Mit Manpages hat es doch auch funktioniert. Naja, meistens. Aber
immerhin, wie bereits an anderer Stelle bemerkt wurde, war das schonmal
der richtige Weg.

> > Wie kann man dem Ziel einer guten und einheitlichen (Linux-)Dokumentation
> > möglichst nahe kommen?
[...]
> 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 :)

Da ist was dran. Technische Einheitlichkeit ist vielleicht gar nicht
erstrebenswert. Aber wie bringt man dann die Inhalte zusammen? Wie kommt
man von der Manpage zum Tutorial und umgekehrt?

Außerdem: Unterschiedliche Arten von Doku können ja gerne
unterschiedliche Dateitypen etc. haben. Aber *gleiche* Arten von Dokus
sollten auch gleich behandelt werden.

Ein interaktives Tutorial kann keine Manpage oder PDF sein. Aber wieso
kann ich mit "man" nicht auch Howtos ansehen? Wieso können API-Docs
keine Manpages sein? (mit memcopy & Co. geht's doch auch!)

Verschiedene Manpages kann man wenigstens aufeinander verweisen lassen,
*ohne* gleich Internet zu benötigen. Es müsste doch sogar *leichter* für
JavaDoc, EpyDoc, Doxygen & Co. sein, Manpages statt HTML-Seiten oder gar
PDF zu erzeugen. Viel weniger Detail-Probleme. Und stattdessen die HTML-
besessenen daran setzen, schicke Manpages -> HTML Konvertierer zu
schreiben, oder Manpages -> LaTeX/PDF. Eben Kräfte bündeln.

Unterschiedliche Tools, gerne. Aber sie müssen zusammenarbeiten.
Standardisierte gemeinsame Schnittstellen gehören doch ebenfalls zum
Unixgedanken.

Ich habe leider immer noch nicht erfahren dürfen, wieso es für API-Docs
und Howtos *besser* sein soll, als HTML statt als Manpages vorzuliegen.
Wo ist der große inhaltliche/konzeptionielle Unterschied? Es gibt doch
riesengroße Gemeinsamkeiten zwischen dem Aufruf eines Kommandozeilen-
tools mit bestimmten Parametern und dem Aufruf einer C- oder Python-
Funktion.


Viele Grüße,

    Volker

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