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

[Steffen Dettmer]

* Volker Grabsch wrote on Tue, Jan 02, 2007 at 03:41 +0100:
> On Mon, Jan 01, 2007 at 10:36:36PM +0100, Steffen Dettmer wrote:
> > Ich hab da auch noch den Vorschlag vom kompliziert zu bedienenden,
> > GUI-freien Kommunikationstool. 
> 
> 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.

IRC ist ja nicht blöd, weil die Werkzeuge nicht konform sind, sondern
weil sich da Herrscharen von 12 jährigen als sonstwas ausgeben und
rumnörgeln und so weiter. Man konnte sich damals irgendwann einfach
nicht mehr unterhalten. Das war kein technisches Problem.

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

Wieso, die GUIs sind doch von Fähigen gemacht. Sie sind nur zu gut. Weil
jeder sie benutzen kann, um das Internet mit einen Forenbeiträgen zu
polluten usw.

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

Gut, mag sein dass meine Vorstellungskraft für ein "Buch im Wiki"
einfach nicht ausreicht. Natürlich könnte man ein "export" oder sowas
machen. Dann ist das für mich aber eher HTML und kein Wiki. Für ein Wiki
ist essentiell, dass ich ändern kann, sonst ist es für mich kein Wiki.
Daher kann ich ein Wiki auch nicht ausdrucken (aber den Inhalt; die
Wiki-Funktion geht dann natürlich verloren - und Features wie z.B:
Historie, die wichtig sein kann, wenn z.B. statt des erwarteten Artikels
nur noch da steht "Linux ist doof" oder so ;)).

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

DokuWiki? Was deutsches? Ich nutze noch ein altes Perl Wiki "TWiki" aus
2000, das nutzt auch RCS. Könnte man ja vuielleicht mal updaten BTW :)

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

(Warum geht das nicht ohne SSL/TLS? Da suggeriert ja so Sicherheit, die
nicht da ist, weil selfsigned cert?! 

ja, ich erinnere mich. Aber sowas muss sich dann auch erst
durchsetzen... MediaWiki ist das von Wikipedia? Fragt sich, inwieweit
das Standard ist, weil es am meisten kennen :)

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

(ja z.B.)

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

Kommt sicher drauf an. Wenn nur 1% der Felder belegt sind, sind Linien
bestimmt eine Gute Idee :)

(Im Allgemeinen mag _ich_ eigentlich gar keine Tabellen. Lieber Text
schreiben, wenn möglich. Manchmal hat man aber wirklich logisch
Tabellen, die sollten dann auch Tabellen sein)

> Man ist viel zu leicht versucht, Doppel-Linien, dickere Linien etc.
> reinzubringen, 

ihh, ja, ist man?!

> obwohl man die dünnen einfach weglassen sollte.
> 
> Das ist also eher ein Feature, kein Bug.

Ahh, Java-Argumentation. Geht nicht, also braucht mans eigentlich gar
nicht, weil man einen Fall gefunden hat, wo's ohne sogar besser ist.

Nee, sorry aber das akzeptiere ich nicht :)

Bleibt die Frage, ob die Tabelle ohne Linien dann übehaupt autoamtisch
richtig formatiert wird. Ich glaub ja nicht, dass die Linien da so einen
UNterschied machen.

> > LaTeX ist ein Satz-System, kein automatischer Formatierer.
> 
> LaTeX ist beides. Um sehr, sehr viele typische Textsatz-Probleme
> kümmert es sich automatisch.

Man bekommt aber Warnungen, wenn was nicht hinhaut (kann man natürlich
ignorieren, klar).

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

Ja, kann man, und genau das ist für mich händisch und nicht automatisch!

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

Dass ist das ganz langsame Beta-SCM? ;) Kenn ich nicht, keine Ahnung.

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

Java ist auch jahrelang im Betrieb und ändert sich bis heute ständig ;)

Eignung hängt halt sehr von den Anforderungen ab. Und die sinken im
Allgemeinen ja gern für die "Masse". Das heisst aber nicht, dass ich
mich dem anschliessen muss :)

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

allgemeine Erfahrung.

> Die Beta-Phase hat SVN längst überwunden. Mercurial, Darcs und GIT
> übrigens auch.

CVS auch.

> > keine Symbole, schlimmer als CVS.
> 
> Geht in Subversion auch, man muss nur bestimmte Properties setzen. 

Laut meiner CVS-Umsteiger-Anleitung muss man die Repo-Versionsnummern
zum mergen benutzen. Properties sind für andere Sachen da, soweit ich
weiss. 

Der .cvsignore-Ersatz über Properties ist IMHO übrigens eine Krankheit.
Warum stört die meisten das bei SVN nicht? Weil man behauptet, es sei
besser, nicht per default alle Dateien im Repo zu haben. Wo kommt das
her? Find ich nämlich nicht. So kann man jedenfalls schön Files
vergessen. Nimmt man automake, klappt dann make distcheck nicht. Warum
stört die Java-Leute das nicht? Na, weil die kein automake haben und mit
dem "ant" leben müssen. Das macht üblicherweise keinen Fehler, wenn ein
paar .java Files fehlen. Die werden dann halt nicht kompiliert und
fehlen im .jar dann halt.

*Meine* Ansprüche erfüllt das nicht. Ich habe die Anforderung, dass
Fehler so früh wie möglich erkannt werden sollen. Also beim kompilieren
(nicht erst wenn nach dem Installieren ein anderes Programm nicht mehr
läuft).

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

Dafür, genau. Und evtl. für Ausdrucke. Aber das mit dem Verteilen (nicht
nur eMail) ist das, was ich in der Praxis lieben gelernt hab.

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

Ich will ja ein Projekt mit mehreren Repositories haben. Nicht paar
Unterverzeichnisse. Das das geht ist ja wohl selbstverständlich. (CVS
kann das auch alles).

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

GIT ist das, was beim Kernel benutzt wird?

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

NEIN! Wie kommst Du denn jetzt da drauf! Mein Beispiel setzte doch
SVN:SCM und mySQL:PostgreSQL in Relation aber nicht SCM:SQL...

Jedenfalls kann man ein SCM nicht einfach mal so wechseln, finde ich.

Obwohl, in meiner Firma wurde auch ein StarTeam gegen ein SVN getauscht,
und dann war die History halt weg. Ein totaler Verlust wäre für mich
inakzeptabel.

Aber wenn man keine Anforderungen hat, ist SVN sicher ok.

GIT oder so anzugucken nützt leider mir so allein auch nicht sooo viel,
weil allein brauch ich das ja auch nicht.

Zu genau dem Thema gabs ja hier auch schon mal einen längeren Thread.

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

Ja? Cool. Ja, hat bestimmt Vorteile.

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

Ja, stimmt.

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

Ja genau, das ist das Problem ;) Da finde mal einen!

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

Ja klar, aber man braucht mindestens einen ;)

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

Die wurden doch gerade neu geschrieben? bzw. auch neuen "--help" Seiten
erzeugt etc?

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

Ja, oder man hätte eine Art übertool, was alles delegiert anzeigt oder
so, aber das Übertool sollte nicht einfach ein Browser sein. Obwohl
ziemlich genau das ja mal die Idee des Browsers war, der Name stimmt ja
noch.

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

doxygen kann das schon ;)

Bloss macht man nicht, weil man bei HTML links kriegt und bei man nicht.

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

Ja, klar. Genau. HTML als "Schnittstelle" ist zu wenig. Geht technisch,
aber nützt nicht soooooo viel, weil bestimmte Sachen halt nicht
automatisch gehen, genau.

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

hyperlinks. Websuche kann das auch gleich. Kannste mit'm Windowsbrowser
drucken.

oki,

Steffen

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