Re: Aufruf zur Toleranz und Vorschläge für Erweiterung der FAQ
Hallo Wilko!
Wilko Fokken schrieb am Sonntag, 24. August 2003:
> On Sat, Aug 23, 2003 at 03:11:20PM +0200, Wilhelm Wienemann wrote:
>> Wilko Fokken schrieb am Samstag, 23. August 2003:
>>
>>>> Am Wed, 20 Aug 2003 12:10:23 +0200 schrieb Stiglbauer Andreas:
^^^^^^^^^^^^^^^^^^^^^^^^^^
>>>>> Die untenstehende Mail brachte das Faß zum Überlaufen und veranlaßt
>>>>> mich, meinen Unmut über den Diskussionsstil in dieser Liste zu
>>>>> äußern.
>>
>> Glaube mir, das haben schon mehrere mit unterschiedlichen Ansätzen
>> versucht. Es mündet nahezu immer und gnadenlos in einen Endlosthread.
>>
> meinen Senf habe ich in dieser Liste, zu diesem Thread zwar auch
> beigetragen, aber den oben erwähnten nicht, auf denselben habe ich
> vielmehr geantwortet; tut aber nichts, Deinen Beitrag fand ich gut.
Den Verfasser des obigen Beitrags habe ich ja, wie sich das gehört,
zitiert. Natürlich hast Du Recht, ich habe wieder mal die Quadratur
des Kreises versucht, die von Dir angesprochene Passage hätte ich
*gesondert* dem ursprünglichen Verfasser 'ins Buch' schreiben sollen. ;-)
[...]
> Dennoch glaube ich, daß kurze, treffende Beispielsausschnitte mit
> typischen Anwendungsbedingungen den Dokumentationsaufwand nur wenig
> erhöhen, dagegen die Lernkurve des Anwenders beträchtlich optimieren
> würden. Nach meiner vagen Erinnerung hatte HP um 1990 die manpages
> seines HPUX vielfach mit kleinen Anwendungsbeispielen ergänzt, und
> nicht nur die Anwender, auch Administratoren pflegten den Aufruf der
> manpages mit der Taste fortzusetzen, die gleich zur letzten Seite
> führte, wo sich die besagten Anwendungsbeispiele fanden.
HPUX ist eines der Unixe, die ich bisher noch nicht nutzen durfte.
Nach meinem bisherigen Kenntnisstand ist Hewlett-Packard mit dem
von Dir zitierten Weg der Abfassung von manpages aber einen Sonderweg
gegangen.
Bisher habe ich die manpages, ähnlich wie Bernd Brodesser es in einem
seiner Beiträge zu diesem Thread schon geschildert hat, als
Schnellübersicht verstanden, die die Befehlsoptionen und Parameter klar
gliedert auflistet und kurz, aber prägnant beschreibt. Einzelne, wenige
manpages folgen aber Deiner Empfehlung wie z.B. 'figlet', 'procmail',
'cdrecord', 'mkisofs' etc.; insgesamt ist das aber eher die Ausnahme.
> Die Erkenntnis: "Ein Bild sagt mehr als tausend Worte" möchte ich
> ergänzen mit: "Ein Beispiel sagt mehr als hundert Definitionen".
> Vor allem versteht man noch unbekannte Definitionen viel leichter, wenn
> man zuvor einen Einstieg in die Programmfunktionen durch kleine Beispiele
> gefunden hat.
Das ist aber gerade das schwierige Unterfangen. Die möglichen Parameter
und Optionen sind selbst bei kleinsten Programmen so vielfältig und
oft konträr zueinander, dass es den Rahmen einer manpage formal
allzuleicht sprengen würde. Einzelne manpages (z.B. bash, csh, vi etc.)
sind trotz strenger Orientierung an die formale Struktur bereits so
aufgebläht, dass man sich oftmals überhaupt nicht traut, diese zu
benutzen. Wenn dann noch eine Vielzahl von Beispielen dokumentiert wäre,
dann wäre die ursprüngliche Handhabung sicher nicht mehr gewährleistet.
IMHO gibts dazu weiterführende und geeignetere Dokumentationen.
Auch die bekannten Buchautoren, die es gewagt haben, sich diesem Thema
zu nähern, sind sehr schnell mit ihren Versuchen auf einzelne prägnante
Beispiele ausgewichen, da sie festgestellt haben, dass eine lückenlose
Darlegung aller Nutzungs- und Kombinationsvarianten sehr schnell ein
ganzes Bücherregal füllen würde.
> Zum Schluß bitte ich noch um Hinweise, wie man sich äußern soll, wenn
> man glaubt, selbst eine Problemlösung gefunden zu haben, die andere
> interessieren könnte.
Auch wenn es manchmal lange dauert und vielleicht auch erst über gewisse
Umwege unter Beweis gestellt wird, so kann man doch resümieren, dass
Qualität sich immer behaupten wird. Das haben nicht nur Dokumentationen,
Diskussionen und Betriebssysteme gemeinsam. :-))
Wenn Du eine Dokumentationsidee hast, die sich als pädagogisch bessere
darstellt, lasse Dich nicht aufhalten und diese in Form von HOWTOs, FAQs
oder auch manpages - möglichst unter GPL - oder gar in einem Buch zu
veröffentlichen.
Manche Autoren guter Dokumentationen wie z.B. Peter H. Ganten, Frank
Ronneburg, Michael Kofler, Jochen Hein, John Goerzen, Ossama Othman,
Michael Bramer, Sebastian Hetze, Dirk Hohndel, Martin Müller, Olaf Kirch
und viele andere haben das - jeder auf seine Weise - treffend unter
Beweis gestellt.
> In dieser Liste scheint mir die ungefragte Veröffentlichung einer
> Problemlösung noch nicht vorgekommen zu sein.
Sorry, dem muss ich widersprechen. Bereits in meinen vorausgegangenen
Beitrag habe ich zum Ausdruck gebracht, dass ich aus mannigfachen
Diskussionen - auch wenn ich daran nicht unmittelbar beteiligt war -
wertvolle Tipps und Hinweise, ja auch viele Problemlösungen für mich
entlehnen und entnehmen konnte. Den unzähligen und den inzwischen
teilweise auch unbekannten Verfassern in dieser und anderen Mailinglisten
sowie Newsgroups sei an dieser Stelle herzlich gedankt!
Dir und allen Mitlesern der Mailingliste einen schönen Sonntag!
Grüße - Wilhelm
--
(°> Wilhelm Wienemann <Wilhelm.Wienemann@t-online.de> -°) -°)
//\ Grüße vom NiederRhein, der Region mit R(h)einKultur /\\ /\\
V_/_ _\_V _\_V
Reply to: