[linux-l] Dokumentenspeicher

[Peter Ross]

On Wed, 4 Oct 2006, Volker Grabsch wrote:

> Aber
> ein riesengroßer Nachteil ist, dass die Dokumentation in
> solch einem Fall nicht mehr die Anforderungen widerspiegelt,
> sondern die Funktionsweise der Software. Das heißt, auch Bugs,
> Denkfehler, etc. sind mit Dokumentiert, aber als Funktionsweise,
> nicht als Fehler.

Das sehe ich nicht so.

Eine Dokumentation soll einen Ist-Zustand beschreiben, nicht einen 
wuenschenswerten, weil:

   - es fuehrt den Nutzer nicht auf Abwege, bis er dann feststellt,
     dass die Software das nicht leistet.

   - es gibt ihm das Gefuehl einer Unehrlichkeit ("die versprechen
     einem das Blaue vom Himmel"), das Vertrauen in die Software 
     schwindet,

     bis der Anwender die Software als feindlich einstuft und nicht mit,
     sondern gegen sie und sie ignorierend Loesungen sucht.

Ich weiss, dass es Leute gibt, die annehmen, so lange Probleme unter der 
Oberflaeche verborgen sind, bis der Kunde sein Geld bezahlt hat, ist alles 
gut. Danach ist er ausgeliefert..

An Arbeitsplaetzen mit solcher Philosophie macht Arbeit keinen Spass, weil 
man ueberall nur auf Unzufriedenheit stoesst. Langfristig tut man sich 
selbst keinen Gefallen, wenn man den Kunden nicht sauber behandelt. Man 
verliert ihn.

> Normalerweise ist es ein guter Indikator für Fehler, wenn ein
> Programm in seinem Verhalten von der Dokumentation abweicht.

Ja, ein Fehler in der Dokumentation..

> Dann herscht nämlich entweder ein Denkfehler/Missverständnis
> vor, das zu neuen Einsichten führt und evtl. zu einer besseren,
> weniger widersprüchlichen Dokumentation. Oder es ist einfach
> ein Bug im Programm.

Die technische Schreiberin ist eben Teil des Testteams, das Feedback ihrer 
Entdeckungen geht in die Weiterentwicklung der Software ein.

> Entsteht die Dokumentation hingegen im Nachhinein, findet diese
> Form der Qualitäts-Sicherung nicht mehr statt. Leider ist das,
> auch im Bereich der freien Software, der Status-Quo. Das heißt
> aber nicht, dass es gut so ist. Größere OpenSource-Projekte
> zeichnen sich vorallem durch bessere Dokumentation aus.

Naja. Manchmal.

Anyway, das Pflichtenheft ist die Spezifikation fuer den Informatiker, es 
hat _nichts_ mit der Anwenderdokumentation zu tun.

Die technischen Dokumentationen, die innerhalb der Softwareentwicklung 
entstehen, sollten wirklich projektbegleitend sein. 

Anwendungsdokumentationen sind ein anderes Paar Schuhe.

Gruss
Peter