lernen:document
no way to compare when less than two revisions
Unterschiede
Hier werden die Unterschiede zwischen zwei Versionen angezeigt.
— | lernen:document [2014-07-13 16:14] (aktuell) – angelegt - Externe Bearbeitung 127.0.0.1 | ||
---|---|---|---|
Zeile 1: | Zeile 1: | ||
+ | ====== Dilemmata der Dokumentation ====== | ||
+ | |||
+ | > Das, was am Anfang wie Gift sein kann, doch am Ende wie Nektar ist und einen zur Selbsterkenntnis erweckt, gilt als Glück in der Erscheinungsweise der Tugend. | ||
+ | >> | ||
+ | |||
+ | Es werden einige Methoden der Dokumentation dargestellt und ihre Vor- und Nachteile erläutert. | ||
+ | Der Text ist nicht als Anleitung zur Dokumentation gedacht. | ||
+ | Im Gegenteil: Dokumentation ist unmöglich. Dennoch müssen wir es versuchen. | ||
+ | |||
+ | Lexikoneintrag: | ||
+ | * Dokument = Urkunde, Beweisstück [Knaur Konversationslexikon 1936] | ||
+ | * lat. documentum = Belehrung, zu docere = Unterricht geben. Infix men = Mittel, also Mittel der Belehrung [Etymologisches Wörterbuch] | ||
+ | |||
+ | ===== Ungeliebte Pflicht ===== | ||
+ | |||
+ | Es scheint paradox: Programmierer heißen Programmierer, | ||
+ | obwohl sie durchschnittlich höchstens zwei Stunden täglich mit Programmieren verbringen. | ||
+ | Dies weiß Fred Brooks [Brooks] zu berichten. Der Mann muss es wissen. | ||
+ | Schließlich war er Projektleiter für das zu seiner Zeit revolutionäre IBM System 360. | ||
+ | Was tun Programmierer in der restlichen Zeit? | ||
+ | Damals war nicht jederzeit Zugang zum Rechner möglich. | ||
+ | Die Maschine war eine knappe Ressource. Allerdings war sie nicht der Engpass. | ||
+ | Selbst heute, mit einem PC an jedem Arbeitsplatz, | ||
+ | " | ||
+ | Sie schaffen in großen Projekten täglich 10-20 endgültige Quelltextzeilen. | ||
+ | Sie schlagen ihre Zeit tot, indem sie Dinge tun, die keinen Spaß machen. | ||
+ | Sie sitzen in Sitzungen, lesen Schriftstücke, | ||
+ | weshalb er neu gelesen werden muss, und verfassen womöglich selber Schriften, | ||
+ | die sie anderen zusenden (müssen). | ||
+ | |||
+ | > Dokumentation ist das Rizinusöl des Programmierens. Die Manager denken, es sei gut für die Programmierer, | ||
+ | > | ||
+ | >> | ||
+ | |||
+ | Die Welt wäre viel schöner, wenn wir nur die Dinge tun könnten, die Spaß machen. | ||
+ | Dabei impliziere ich, dass das Programmieren selbst Spaß macht. | ||
+ | Im Internet findet sind auch die Bemerkung: Dokumentation ist wie Sex. | ||
+ | In gewisser Weise stimmt das auch. | ||
+ | Als Weinberg 1971 die " | ||
+ | stellte er fest, dass es keinen Weg gibt, Programmierer zu zwingen, | ||
+ | gute Dokumentationen zu produzieren. Zwingen kann man einige Programmierer, | ||
+ | irgendwelche Dokumentationen zu erzeugen, so wie Kinder gezwungen werden, | ||
+ | Rizinusöl zu sich nehmen. Es gibt jedoch zuviele Möglichkeiten, | ||
+ | die Sache zu sabotieren und zu entwerten. Haben die Beteiligten nichts davon, | ||
+ | wird es auf minimale Weise erledigt. Hat es jedoch gute Effekte, | ||
+ | gibt es kaum Möglichkeiten, | ||
+ | |||
+ | ===== Quelltext und Dokumentation sind nicht dasselbe ===== | ||
+ | |||
+ | Form und Inhalt sollten eine ästhetische Einheit bilden. Leider wird dieses Ideal nur selten erreicht. Der " | ||
+ | |||
+ | <code c choochoo.c> | ||
+ | extern int | ||
+ | errno | ||
+ | ;char | ||
+ | grrr | ||
+ | ; | ||
+ | argv, argc ) int argc , | ||
+ | | ||
+ | #define x int i, | ||
+ | x ;if (P( ! i ) | cc[ ! j ] | ||
+ | & P(j )> | ||
+ | ; for (i= 0;; i++ ); | ||
+ | _exit(argv[argc- 2 / cc[1*argc]|-1<< | ||
+ | P ( a ) char a ; | ||
+ | /* - by E ricM arsh | ||
+ | </ | ||
+ | Was produziert es? | ||
+ | |||
+ | Ziel des IOCCC-Wettbewerbs ist nicht, gute Dokumentation zu schulen. | ||
+ | Er leuchtet vielmehr dunkle Ecken aus: | ||
+ | |||
+ | * Schreibe den obskursten, verhunztesten C-Quelltext. | ||
+ | * Demonstriere die Wichtigkeit eines Programmierstils (ironisch) | ||
+ | * Teste Compiler mit unüblichem Quelltext | ||
+ | * Verdeutliche Eigenheiten von C-Programmen | ||
+ | * Forum für " | ||
+ | |||
+ | Brian Westleys " | ||
+ | Als Erläuterung gab er an, dass dieses Programm die Kreiszahl pi berechnet; | ||
+ | für genauere Werte brauche man nur ein größeres Programm schreiben. | ||
+ | Das Programm verschleiert (obfuscate = verhüllen) kaum, | ||
+ | dass die Berechnung mittels der Kreisflächenformel $A=\pi*d^2/ | ||
+ | Es erfordert jedoch etwas Mühe, bis man dies erkennt. Es funktioniert nur, | ||
+ | falls der Präprozessor aus zwei aufeinander folgenden Minuszeichen ein Doppelminus-Token erzeugt: | ||
+ | |||
+ | <code c pi.c> | ||
+ | #define _ -F< | ||
+ | int F=00, | ||
+ | { | ||
+ | _-_-_-_ | ||
+ | | ||
+ | _-_-_-_-_-_-_-_-_-_-_-_ | ||
+ | _-_-_-_-_-_-_-_-_-_-_-_-_-_ | ||
+ | | ||
+ | | ||
+ | _-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_ | ||
+ | _-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_ | ||
+ | _-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_ | ||
+ | _-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_ | ||
+ | | ||
+ | | ||
+ | _-_-_-_-_-_-_-_-_-_-_-_-_-_ | ||
+ | _-_-_-_-_-_-_-_-_-_-_-_ | ||
+ | _-_-_-_-_-_-_-_ | ||
+ | _-_-_-_ | ||
+ | } | ||
+ | </ | ||
+ | Soweit zum Spaß. | ||
+ | |||
+ | ===== Quelltext ist nicht alles ===== | ||
+ | |||
+ | Nur selten reicht der Quelltext aus, um seine Wirkung zu verstehen. | ||
+ | Aus diesem Grund wird er mit Kommentaren versehen. | ||
+ | Der richtige Einsatz von Kommentaren erfordert Erfahrung: | ||
+ | |||
+ | <code c> | ||
+ | for(i=0; i< | ||
+ | feld[i] = 0; // auf Null setzen | ||
+ | </ | ||
+ | |||
+ | Hier wurde einem C-verständigen Leser keine zusätzliche Information gegeben. | ||
+ | Der Kommentar soll nicht wiederholen, | ||
+ | Der Quelltext ist selbsterklärend. Da er von Programmierern gelesen wird, | ||
+ | sollte jener auch verstehen, was getan wird. Im Quelltext steht jedoch nicht, | ||
+ | warum das Feld initialisiert wird. | ||
+ | Dies muss eine Dokumentation oder ein Kommentar leisten. | ||
+ | Der Programmierer braucht die Übersicht, in welchem Rahmen das Feld verwendet wird, | ||
+ | unter welcher Einsatzbedingung die Feldwerte zu nullen sind. | ||
+ | Das kann Quelltext nicht leisten. | ||
+ | Auch technische Dokumentierwerkzeuge werden das nicht erkennen können. | ||
+ | Könnten sie es, wäre vermutlich auch der Beruf des Programmierer überflüssig. | ||
+ | Solange künstliche Intelligenz nicht als Ersatz für natürliche Dummheit verfügbar ist | ||
+ | (ich hoffe, das bleibt noch eine Weile so), solange nimmt uns jedoch keiner diese Mühe ab. | ||
+ | |||
+ | Dokumentiere das Warum; das Wie steht im Quelltext. | ||
+ | Eine Ursache, dass Dokumentieren ungeliebt ist, steckt darin. | ||
+ | Wir müssen nachdenken und Rechenschaft ablegen, nicht, was wir tun, | ||
+ | sondern vor allem, warum. Wir müssen Beweggründe offenlegen, | ||
+ | die zur Entscheidung für ein Vorgehen führten. Dokumentieren ist aufwendig. | ||
+ | Dies beim Implementieren zu erledigen, | ||
+ | widerspricht dem Streben nach Zerlegung in Teilaufgaben. | ||
+ | Warum soll ich dokumentieren, | ||
+ | ob etwas überhaupt funktioniert? | ||
+ | der den Code zu Gesicht bekommt? | ||
+ | Andere interessieren sich nur für die Schnittstellen. | ||
+ | Dafür gibt es Dokumentations-Generatoren... | ||
+ | |||
+ | ===== Wo steckt die Dokumentation im System? ===== | ||
+ | |||
+ | Doku-Generatoren nutzen in den Quelltext eingebaute Kommentare. | ||
+ | Ausführbare Dokumente gehen den umgekehrten Weg. | ||
+ | Literate Programming und Case Tools setzen eine eigene Ebene darüber. | ||
+ | |||
+ | < | ||
+ | +--------\ | ||
+ | | Quelle | --------------> | ||
+ | +--------+ | ||
+ | |||
+ | +--------\ | ||
+ | | Quelle | < | ||
+ | +--------+ | ||
+ | |||
+ | | ||
+ | | WEB-Dokument / Case Tool | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | Quelle | | Dokumentation | | ||
+ | | ||
+ | </ | ||
+ | Alle diese Ansätze verfolgen ein gemeinsames Ziel: One Source. | ||
+ | Ansonsten bleibt nur die Parallel-Entwicklung mit der Gefahr: | ||
+ | Stimmen Quelltext und Dokumentation nicht überein, sind vermutlich beide falsch. | ||
+ | |||
+ | ===== Dokumentation aus dem Quelltext ===== | ||
+ | |||
+ | Hunt und Thomas [Hunt] geben folgenden Rat für den pragmatischen Programmierer: | ||
+ | Wiederhole dich nicht! Der Quelltext ist das, worauf es ankommt. | ||
+ | Wie etwas getan wird, steht im Quelltext. | ||
+ | Variablen- und Typnamen sollten sorgfältig und bedeutungsvoll gewählt werden. | ||
+ | Irreführende Namen sind noch schlimmer als bedeutungslose: | ||
+ | Bedenke: Der Quelltext wird hunderte Male gelesen, aber (hoffentlich) nur wenige Male geschrieben. | ||
+ | Kommentare sollten das Geschriebene nicht wiederholen, | ||
+ | warum dies so getan wird. Handwerkliche Kompromisse können erläutert, | ||
+ | Stolperstellen markiert werden, | ||
+ | Dinge, für die sonst nirgends Platz in der Dokumentation vorgesehen ist. | ||
+ | Gut dokumentierter Quelltext enthält | ||
+ | |||
+ | * einen einleitenden Kommentarkopf für die Datei, der zumindest den Zweck des Quelltextes beschreibt, der Name des Autors für Rückfragen; | ||
+ | * eine Erläuterung für jede Klasse und | ||
+ | * eine Erläuterung für jede (nicht triviale) Methode oder Funktion. | ||
+ | |||
+ | Wie diese Kommentare auszusehen haben, kann in Codierungsstandards festgelegt sein. | ||
+ | Es wird auch beeinflusst von der Art der Systeme, mit denen gearbeitet wird. | ||
+ | Editoren sind empfänglich für bestimmte Zeichenfolgen. | ||
+ | Falten-Editoren können Teile des Quelltextes aus- oder einblenden. | ||
+ | Versionskontrollsysteme können Kommentare in den Quelltext einbauen etc. | ||
+ | Dokumentationsgeneratoren können aus solchen Kommentaren Referenz-Dokumente herausziehen. | ||
+ | Zum Java-Entwicklungssystem gehört Javadoc. | ||
+ | Für C++ gibt es neuerdings ähnliche Systeme (Doxygen). | ||
+ | Ein Java-Dokumentationskommentar-Beispiel: | ||
+ | |||
+ | <code java> | ||
+ | /** | ||
+ | * Generate the inverse of a quadratic matrix. | ||
+ | * | ||
+ | * @param | ||
+ | * @return the inverse matrix, if matrix is not singular. | ||
+ | * @exception Singular When determinant(matrix) is zero. | ||
+ | * | ||
+ | * @see QuadraticMatrix | ||
+ | * @see Singular | ||
+ | * @see LinearAlgebra | ||
+ | * @author R. Richter | ||
+ | * @version 0.95, 2002-10-22 | ||
+ | */ | ||
+ | public QuadraticMatrix inverse(QuadraticMatrix matrix) throws Singular; | ||
+ | </ | ||
+ | |||
+ | Der Vorteil dieser Technik liegt darin, dass stets eine aktuelle, | ||
+ | vollständige Referenz der Klassenschnittstellen generiert und | ||
+ | auch online verbreitet werden kann. | ||
+ | Diese HTML-Referenzdokumente können Querverweise auf andere Module enthalten | ||
+ | und so ein "Netz des Wissens" | ||
+ | Ein Vorteil des Verfahrens ist, dass die Information über eine Funktion, | ||
+ | Methode oder Klasse an einer Stelle lokalisiert ist | ||
+ | (Prinzip: one source --- wiederhole dich nicht). | ||
+ | Das mindert die Gefahr, dass Quelltext und Dokumentation sich auseinander entwickeln. | ||
+ | |||
+ | Der Pferdefuß liegt in dem Wort kann. Dokumentation ist nicht kostenlos. | ||
+ | Man muss einen solchen Stil aktiv pflegen. | ||
+ | Unsere Werkzeuge sollten das erleichtern. | ||
+ | Ordentliche Editoren für Programmierer sind in der Lage, | ||
+ | für diesen Zweck vorgefertigte Kommentar-Bausteine mit wenigen Tastendrücken in den Quelltext einzufügen. | ||
+ | |||
+ | ===== Quelltext aus dem Dokument ===== | ||
+ | |||
+ | Jedes Modul, jede Klasse, jede Funktion, | ||
+ | jede globale Variable für sich getrennt zu erläutern, ist eine Methode. | ||
+ | Sie hat aber den Nachteil, | ||
+ | dass diese Kommentare nur ein loses Netz von Referenzdokumenten ergeben. | ||
+ | Netze bergen auch die Gefahr, sich darin zu verheddern. | ||
+ | Ohne Leitdokumente kann sehr schnell die Orientierung verloren gehen. | ||
+ | Es gibt eine entgegengesetzte Methode, die versucht, | ||
+ | den Quelltext logisch aufeinander folgend in einem unterrichtenden Stil | ||
+ | (im Wortsinn als Dokument) zu entwickeln. | ||
+ | Diese Idee wurde von Donald E. Knuth für die Entwicklung des Textsatzsystems TEX benutzt | ||
+ | und als " | ||
+ | Aus einem WEB-Dokument kann sowohl den Quellcode zusammengesetzt (tangle = verknoten) | ||
+ | als auch eine druckfertige Dokumentation erstellt werden (weave = verweben). | ||
+ | Die beiden Prozesse Tangle und Weave erzeugen unterschiedliche Sichten (Projektionen) | ||
+ | eines einheitlichen Dokumentes. Obwohl die Idee verlockend ist, | ||
+ | hat sie sich nicht auf breiter Front durchgesetzt. | ||
+ | Es gibt nur eine relativ kleine Gemeinde von Nutzern und einen Haufen Propaganda. | ||
+ | Offensichtlich ist der Aufwand, das WEB-System zu verstehen, sehr hoch. | ||
+ | Der Schreiber muss drei Sprachen gleichzeitig beherrschen und auseinander halten: | ||
+ | die Programmiersprache, | ||
+ | Ausführbare Dokumente lassen sich auch ohne so großen Aufwand produzieren. | ||
+ | ASCII-Klartext (HTML, LaTeX, troff oder RTF) mit einigen Textmarken reicht vollkommen aus: | ||
+ | |||
+ | <code cpp> | ||
+ | //: hallo.cpp : Hallo-Programm - R.Richter 2002-10-22 | ||
+ | #include < | ||
+ | using namespace std; | ||
+ | |||
+ | int main() | ||
+ | { | ||
+ | cout << " | ||
+ | return 0; | ||
+ | } | ||
+ | //~ <- Ende des Quelltextes | ||
+ | </ | ||
+ | |||
+ | Einfache Werkzeuge (Perl oder [[anwenden: | ||
+ | sind in der Lage, | ||
+ | so markierte Quellen für die Übersetzung aus dem Dokument herauszuziehen. | ||
+ | Gerade für Lehrbücher ist diese Technik hervorragend geeignet, um sicherzustellen, | ||
+ | dass die Programmbeispiele tatsächlich lauffähigen Quelltext ergeben [Eckel]. | ||
+ | Es gibt einen Haufen schlecht übersetzter Bücher, | ||
+ | bei denen die automatische Rechtschreibkorrektur die Quelltexte entstellt: | ||
+ | |||
+ | If(! anwender_besitzt_hund) | ||
+ | Cout << "Sie sollten sich einen Hund anschaffen" | ||
+ | |||
+ | ...der den Übersetzer von [Jamsa] beißt. | ||
+ | So etwas Ärgerliches kann man nicht als Lehrbuch bezeichnen. | ||
+ | Textbearbeitungsprogramme sind nicht nur "zu intelligent" | ||
+ | Sie speichern die Dokumente auch noch in einem herstellereigenen (proprietären), | ||
+ | meist nicht oder nicht ausreichend dokumentierten (da haben wir' | ||
+ | das sich mindestens aller zwei Jahre so ändert, | ||
+ | dass vorhergehende Textversionen nicht mehr bearbeitet werden können. | ||
+ | Um meine 15 Jahre alte Dissertation heute noch mal ausdrucken, | ||
+ | müsste ich die alte Textverarbeitung nochmal aufspielen, | ||
+ | evtl. das Betriebssystem " | ||
+ | der alle mühevoll kontrollierten Seitenumbrüche durcheinanderwirft. Nein, danke. | ||
+ | Es ginge vermutlich schneller, sie nochmal in LaTeX zu setzen... | ||
+ | LaTeX ist seit 20 Jahren stabil. | ||
+ | |||
+ | ===== Case Tools setzen noch eins drauf ===== | ||
+ | |||
+ | Case Tools beantworten die Frage nach der Herkunft von Quelltext und Dokumentation ganz anders. | ||
+ | Dem Programmierer (darf man den hier noch so nennen?) oder Entwickler | ||
+ | wird eine herstellerspezifische Oberfläche angeboten, | ||
+ | auf der unterschiedliche Sichten der entstehenden Software-Lösung zu bearbeiten sind. | ||
+ | Dahinter steckt meist ein kompliziertes System aus proprietären | ||
+ | (und meist nicht dokumentierten) Binärdateien, | ||
+ | d.h. auf Knopfdruck, Dokumentationen zusammengestellt oder auch Quellcode generiert wird. | ||
+ | |||
+ | Als die Idee der Case Tools aufkam, schien die Verheißung, | ||
+ | nie wieder unverständlichen Quelltext tippen zu müssen, die Produktivität zu erhöhen. | ||
+ | Natürlich erst, nachdem man sich in das neue System eingefuchst hat. | ||
+ | Fred Brooks hat uns gewarnt: Es gibt keine " | ||
+ | die uns der Mühen enthebt, keinen Stein der Weisen [Brooks2]. | ||
+ | |||
+ | Das Problem der Case Tools ist dasselbe wie das der WYSIWYG-Texteditoren: | ||
+ | "What You See Is All You Get." [Kernighan] | ||
+ | Man sieht immer nur eine Sicht, da der Bildschirm immer zu klein ist. | ||
+ | Auch kann man innerhalb des Systems nicht darlegen, was und vor allem, | ||
+ | warum man etwas getan hat. Dies muss man sich wieder außerhalb notieren. | ||
+ | Damit stehen wir vor demselben Problem, nur auf höherem Niveau. | ||
+ | Nebenbei noch eine Preisfrage: Mit welchem System werden Case Tools entworfen? | ||
+ | |||
+ | Man erhält innerhalb des Systems keine Übersicht, ob der Entwurf / | ||
+ | die Umsetzung abgeschlossen ist. Den generierten Quelltext durchzuarbeiten, | ||
+ | ist meist grauenhaft, da dieser von einer Maschine für eine Maschine erzeugt wurde, | ||
+ | ohne Rücksicht auf eventuelle menschliche Leser. | ||
+ | Wird dort doch ein Fehler gefunden, bleibt die Schwierigkeit, | ||
+ | die entsprechende Stelle im Case Tool zu lokalisieren. | ||
+ | |||
+ | Case Tools müssen, um erfolgreich zu sein, häufig gestellte Probleme nachbilden. | ||
+ | Die Entwickler von Case Tools stehen im Zweispalt, | ||
+ | entweder eine Sache richtig oder viele nur halb zu machen. | ||
+ | Bei der Entwicklung bleibt meist keine Zeit, für seltene Probleme Lösungen vorzusehen. | ||
+ | Case Tools sind begrenzte, geschlossene Systeme. | ||
+ | Sie können nur mit wenigen Sprachen, Compilern, Betriebssystemen zusammenarbeiten. | ||
+ | Es besteht meist keine Möglichkeit, | ||
+ | |||
+ | Proprietäre Binärformate werden zum Hindernis beim Versions- und System-Wechsel. | ||
+ | Sie verstoßen gegen die im vorigen Abschnitt geschilderte schmerzvolle Erfahrung: | ||
+ | Nutze nur menschlich lesbare ASCII-Formate für wichtige Daten. | ||
+ | |||
+ | ===== Das System zerbricht ===== | ||
+ | |||
+ | Das Ideal, alles im selben System zu dokumentieren, | ||
+ | Eine Idee ist schnell skizziert. Dafür reichen manchmal wenige Bleistiftstriche auf Papier. | ||
+ | Muss die Idee in elektronischer Form gespeichert werden, steht die Frage: | ||
+ | textliche Beschreibung oder Bild? Ein Text ist als ASCII-Text speicherbar, | ||
+ | kann aber missverständlich formuliert sein. | ||
+ | Ein Bild kann komplexere Zusammenhänge besser veranschaulichen. | ||
+ | Ein Bild ist soviel wert wie tausend Worte. | ||
+ | Manchmal kostet ein Bild auch mehr als 2 KByte (1 Computerwort = 2 Byte). | ||
+ | Statt die Bleistiftskizze in die Tat umzusetzen, verbringen wir viel Zeit damit, | ||
+ | das Bild zu bearbeiten, denn hat man das Bild dann schon in elektronischer Form, | ||
+ | möchte man es gern auch perfekt, dokumentationsbereit, | ||
+ | Bilder, egal, ob in Pixelform (eingescannte Skizze) | ||
+ | oder im Vektorformat sind aber das Paradebeispiel für inkompatible Dateitypen. | ||
+ | Gerade in diesem Bereich fällt die Normierung ausgesprochen schwer. | ||
+ | |||
+ | ===== Medien-Brüche ===== | ||
+ | |||
+ | Doch gibt es einen viel gewichtigeren Grund, | ||
+ | warum geschlossene Dokumentationssysteme nicht funktionieren. | ||
+ | Dokumentation beginnt schon lange vor der Implementierung, | ||
+ | vor dem Einsatz von Case Tools. | ||
+ | Das Dokumentationsproblem betrifft alle Phasen des Entwicklungsprozesses: | ||
+ | |||
+ | | Analyse | Dokumentation | Kommunikation mit Kunden, Pflichtenheft | | ||
+ | | Entwurf | " | Analyse-Ergebnisse, | ||
+ | | Codierung | " | Quelltexte, Bibliotheksreferenzen, | ||
+ | | Test | " | Testfälle, Testverfahren, | ||
+ | | Einsatz | " | Installationsverfahren, | ||
+ | | Wartung | Dokumentation | Fehlerbehebungsprotokolle, | ||
+ | |||
+ | Und Dokumentation richtet sich nicht an eine homogene Gruppe von Adressaten. | ||
+ | Manager, Analytiker, Projektleiter, | ||
+ | Service-und Wartungspersonal, | ||
+ | (die letzten drei Gruppen sind nur im Heimbereich identisch!). | ||
+ | Unter den Bedienern wiederum gibt es unterschiedliche Schulungsgrade. | ||
+ | Manchem ist schon mit einer Kurzeinführung (" | ||
+ | Es gibt Bedienhandbücher, | ||
+ | Referenzhandbücher, | ||
+ | manchmal aber schwer verständlich aufführen, und solche, | ||
+ | die stumpfsinnig Menüpunkt für Menüpunkt aufzählen | ||
+ | (meist entstanden während eines dreiwöchigen Bade- und Arbeitsurlaubs | ||
+ | eines " | ||
+ | |||
+ | Nicht jeder Programmierer ist gleichzeitig ein begnadeter technischer Schreiber. | ||
+ | (Ich will nicht gleich Schriftsteller sagen.) | ||
+ | Es wäre ideal, aber die Welt ist nicht so. | ||
+ | Nicht jeder Dokumentierer muss auch gleichzeitig die Software | ||
+ | bis in den letzen Winkel auswendig kennen. | ||
+ | Dies schaffen schon die Anwendungsprogrammierer nicht. | ||
+ | Auch da herrscht Arbeitsteilung. Ohne diese wären große Systeme nicht zu bauen. | ||
+ | Alleskönner sind so teuer, dass keine Firma sich leisten kann, | ||
+ | nur solche zu beschäftigen, | ||
+ | Dann jedoch müssen Verfahren gefunden werden, | ||
+ | wie die Information von den Programmierern zu den Dokumentatoren kommt. | ||
+ | Professionelle Dokumentation muss nicht vom Programmierer allein getan werden, | ||
+ | aber sie sollte mit Unterstützung des Programmierers erfolgen. | ||
+ | Hier haben wir wieder psychologische und manchmal betriebsorganisatorische Barrieren: | ||
+ | Wer bezahlt dafür? Zeit ist die kostbarste Ressource. | ||
+ | Dokumentation als den letzten, | ||
+ | unter Zeitdruck vernachlässigbaren Schritt des Entwicklungsprozesses anzusehen, | ||
+ | ist ein beliebter Fehler, der im traditionellen, | ||
+ | |||
+ | Analyse > Entwurf > Umsetzung > Test > Dokumentation > Einsatz. | ||
+ | |||
+ | Es gibt inzwischen bessere Vorgehensmodelle. | ||
+ | Dokumentation muss während des Prozesses erfolgen. | ||
+ | Nach einem halben Jahr kann sich niemand mehr erinnern. | ||
+ | Ein ständiger Abgleich mit den Entwurfszielen ist notwendig. | ||
+ | |||
+ | Dokumentation und Programm dürfen sich nicht auseinander entwickeln. | ||
+ | Tun sie es, und sehr oft ist das der Fall, | ||
+ | kann dies das Scheitern des Projektes nach sich ziehen. | ||
+ | |||
+ | Gedruckte Dokumente stellen immer einen Schnappschuss des Systems dar. | ||
+ | Das System entwickelt sich danach weiter. Sehr oft sind dann Dokumente veraltet. | ||
+ | Mit Hypertextsystemen und weltweiten Netzen können Online-Dokumente zeitnah abgefragt werden. | ||
+ | Hier können Automatisierungstechniken mit Erfolg eingesetzt werden. | ||
+ | Allerdings kommt diese Technik auch nicht kostenlos daher. | ||
+ | Die Frage ist immer: Wer bezahlt dafür? Wie hoch ist der Preis? | ||
+ | Was ist die Alternative? | ||
+ | |||
+ | ===== Technische Lösungen für soziale Probleme? ===== | ||
+ | |||
+ | > Der Mensch wird auf die Dauer zu dem, mit dem sich sein Geist beschäftigt. Das gilt selbstverständlich auch für Leute, deren Aufgabe darin besteht, tagtäglich über Dinge nachzusinnen, | ||
+ | >>--- Joseph Weizenbaum | ||
+ | |||
+ | Oder um einen alten Witz zu zitieren: | ||
+ | Was macht der Programmierer, | ||
+ | |||
+ | Programmierer und Techniker allgemein neigen dazu, | ||
+ | für Problemstellungen technische Lösungen zu suchen, auch dann, | ||
+ | wenn es allgemein (zwischen-) menschliche, | ||
+ | Weil demokratische Wahlergebnisse knapp oder umstritten sein können, | ||
+ | sollen wir sie einer Wahlmaschine übertragen? | ||
+ | deren Ergebnis in Frage zu stellen? Weil Terroristen Flugzeuge entführen, | ||
+ | sollen die Flugzeuge ferngesteuert werden. | ||
+ | Flugleitzentralen zu besetzen oder Funkstrecken zu stören ist genauso möglich. | ||
+ | Weizenbaum kritisiert zurecht, daß wir technikzentriert denken. | ||
+ | Er sagt sogar: Soziale Probleme sind generell nicht lösbar, | ||
+ | auch nicht mit technischen Mitteln, denn es sind Probleme, | ||
+ | die aus den Eigenheiten der Menschen und ihren Beziehungen untereinander entstehen. | ||
+ | |||
+ | Dokumentation dient der Kommunikation und ist damit ein soziales und psychologisches Problem. | ||
+ | Das Dokumentationsproblem ist vermutlich nie lösbar. | ||
+ | Dennoch müssen wir immer wieder Wege finden, | ||
+ | wichtige Informationen für die Nutzung unserer Systeme verfügbar zu machen. | ||
+ | Technische Lösungen können uns dabei allenfalls unterstützen. Nutzen wir sie. | ||
+ | |||
+ | ==== Quellen ==== | ||
+ | |||
+ | * [Brooks] Frederick P. Brooks jr.: The Mythical Man-Month. Addison-Wesley, | ||
+ | * [Weinberg] Weinberg: The Psychology of Programming. Dorset House, New York (1971). Silver Anniversary Edn. (1998). ISBN 0-932633-42-0 | ||
+ | * [IOCCC] The International Obfuscated C Code Contest. http:// | ||
+ | * [Hunt] Andrew Hunt, David Thomas: The Pragmatic Programmer. AddisonWesley, | ||
+ | * [TeX] Donald E. Knuth: The TeX Book. Addison-Wesley, | ||
+ | * [Jamsa] Kris Jamsa: C++ Von Null auf Hundert. Elektor, Aachen (2000), S. 83. | ||
+ | * [Brooks2] Frederick P. Brooks jr.: No Silver Bullet. IEEE Computer Vol 20, 4(1987). Nachdruck in: [Brooks]. | ||
+ | |||
+ | Weiterführende Literatur: | ||
+ | |||
+ | * [Thaller] Georg Erwin Thaller: Software-Dokumente. Heise, Hannover (1995). ISBN-88229-057-9 | ||
+ | |||
lernen/document.txt · Zuletzt geändert: 2014-07-13 16:14 von 127.0.0.1