Startseite

Einleitung

Dokumentation für den Endanwender

System-Dokumentation

Projektdokumentation mit SoDoM

Zusammenfassung

Literaturverzeichnis

Online-Folien

Kapitel 1 - Dokumentation für den Endanwender

• Motivation
• Klassische Tutorien
• Minimalist Documentation

• Guidelines von John M. Caroll

• Hypertext
• Mustergestützte Softwaredokumentation

• Was ist ein Dokumentationsmuster?

• Muster in der Dokumentation von Frameworks

• Ausblick

Motivation

Aufgrund des braindrain-Effektes, d.h. dem häufigen Wechsel von Entwicklern und der derzeitigen Arbeitsmarktsitutation im Bereich der Informationstechnologie, ergibt sich häufig das Problem, daß neue Mitarbeiter in ein bestehendes Entwicklerteam eingearbeitet werden müssen.

Oft treten Probleme bei der Einarbeitung in neue Entwicklungsumgebungen auf, da diese zumeist hoch-komplexe Softwaresysteme darstellen. Ein Hauptanliegen der Softwareindustrie ist es, diese Einarbeitungszeit möglichst gering zu halten. Der Qualitätsaspekt dieser Einarbeitung darf dabei natürlich nicht außer acht gelassen werden.

Diese Probleme können durch hochwertige Anwenderdokumentation, oft in Form von Tutorien, gelöst oder zumindest teilweise gelöst werden.

1.1 Beschreibung klassischer Tutorien

Klassische Tutorien arbeiten meistens mit der Methode der Schritt für Schritt Anweisungen. Experimente von John M. Caroll haben allerdings gezeigt, daß für die meisten Menschen diese Schritt für Schritt Anweisungen nur unzureichend effektiv sind. Caroll wies darauf hin, daß der Mensch viel effektiver auch schwierige Sachverhalte lernen und erfassen kann, wenn er die Reihenfolge selbstmotiviert bestimmen kann. Dies schließt auch die Bestimmung des Lerntempos ein.

Ein typisches Beispiel für ein Tutorial nach klassischem Stil zeigt dieser Screenshot, der von der Microsoft Word Hilfe erstellt wurde.

Klassisches Schritt für Schritt Tutorial

John M. Caroll hat aus den Ergebnissen seiner Studien, die zeigten, daß traditionelle Schritt für Schritt Anweisungen zu ineffektiv sind, Guidelines abgeleitet, die das Erstellen effektiverer Tutorien erleichtern sollen. Diese werden bei der "Minimalist Documentation" berücksichtigt.

1.2 Minimalist Documentation

Minimalist Documentation ist aus der Idee geboren worden, daß der Leser sofort zu den Informationen, die für die Lösung seines Problemes notwendig sind, kommen will. Was der Leser nicht will ist, daß er stattdessen erst einige Seiten für ihn irrelevante Informationen lesen muß, wie es häufig noch die Regel ist. Folge ist, daß der Leser erst zeitaufwendig die notwendigen Informationen suchen muß. Ferner muß er entscheiden, ob die jeweilige Informationen seiner Problemstellung überhaupt entspricht.

Aufbauend auf Carolls Studien versucht die Methode der "Minimalist Documentation" dem Leser durch kurze Seiten, beziehungsweise sogenannten Index Cards, genau die Informationen zu geben, die er für die Lösung seines Problemes braucht. Dabei ist die Reihenfolge beliebig, das heißt, sie kann selbstmotiviert vom Leser gesteuert werden.

Da diese Methode nur kurze und auf das Wesentliche beschränkte Informationen liefert, ergibt sich eine Art von Struktur, die es erlaubt auch größere Probleme zu lösen. Dazu werden Verweise (neudeutsch: links) zwischen den einzelnen Seiten eingesetzt. Als ideales Medium, um diese Verweistechnik zu unterstützen hat sich die HTML (Hypertext Markup Language) herausgestellt.
Aufbauend auf Carolls Studien sind viele Ansätze gemacht worden, die Tutorien effektiver zu gestalten. Hier nun die Ergebnisse, die Caroll aus seinen Studien gewonnen hat:

Klassische Tutorien, die mit der Schritt für Schritt Methode arbeiten und rein textorientiert sind, haben sich indes als ineffektiv herausgestellt. Hingegen sind web-basierte Methoden, die ein selbstmotiviertes Navigieren des Anwenders erlauben, weit effektiver.(siehe dazu auch Punkt 4 der Guidelines).
Ein ideales Medium, um selbstmotiviertes Navigieren zu unterstützen bietet das Internet. Die dort verwendete Programmiersprache HTML(Hypertext Markup Language) bietet dazu viele Möglichkeiten an.

1.3 Hypertext

Der Einsatz von Hypertext birgt viele Vorteile gegenüber den klassischen Tutorien, die physisch getrennt von der Anwendung sind. Gedruckte Tutorien haben den Nachteil, daß ein Navigieren und Springen nicht so ermöglicht wird, wie dies unter Hypertext möglich ist. Außerdem lassen sich mit Hilfe von Hypertext die Ansätze von Minimalist Documentation und somit auch die Guidelines von John M. Caroll besser und leichter realisieren. Bei Bedarf ist auch eine umfassendere Darstellung des Problemes vorstellbar, da das Internet einen nahezu grenzenlosen Datenbestand an Informationen anbietet.

Allerdings kann dies auch mit Nachteilen verbunden sein. Die Dokumentation online verfügbar zu machen bedeutet nicht automatisch, daß sie auch besser oder lesbarer ist. Bei vielen Dokumentationen oder Web-Seiten stürzt ein wahres Bombardement an Effekten auf den Leser ein. Da werden Java-Applets und Java-Scripts geladen, animierte Gif-Bilder laden dazu ein dem Autoren eine e-mail zu schicken, Laufschriften informieren über Neuigkeiten und und und...

Für eine Werbeseite mag dies gerechtfertigt erscheinen, nicht so jedoch für eine Dokumentation. Sie sollte sich auf das Wesentliche beziehen und die INFORMATION beziehungsweise DOKUMENTATION in den Vordergrund stellen und nicht durch irgendwelche übertriebenen Effekte vom Wesentlichen ablenken. Hintergrund ist, daß der Leser sehr schnell von animierten Bildern abgelenkt wird. Dies gilt auch für diese Arbeit, in der deshalb bewßt auf allzuviele animierte Bilder verzichtet wurde.

Ich denke dieses Zitat von Dan Sheppard macht das Problem deutlich:

Paper is calm. It looked for while that paper could be augmented calmly, with hypertext, which allowed cross-referencing, something paper wasn't good at. But look at a typical corporate web-page now, it appears to be in a state of constant alarm, like a Vietnam Veteran running knife in hand, screaming, through the University Library. Calm is good.

Wie sich der Einsatz sowohl von Hypertext, als auch von den Guidelines von John M. Caroll auf die Gestaltung von Tutorien moderner Software ausgewirkt hat, möchte ich nun an einigen Beispielen belegen:

Die Abbildung zeigt einen Screenshot aus dem Hilfesystem des (früher Borland heute Inprise) JBuilder. Dies ist eine Entwicklungsumgebung für JAVA.

Deutlich kann man erkennen, daß ein selbstmotiviertes Navigieren innerhalb der Dokumentation sehr leicht möglich ist.(siehe dazu links oben auf die Pfeilsymbole). Ansonsten unterscheidet sich dieses Hilfesystem nicht sehr stark von klassischen Schritt für Schritt Anweisungen. Jedoch wurde auf eine lange Einleitung verzichtet, so daß der Anwender schnell zu der Lösung seines Problemes findet. Eine Suchfunktion am linken unteren Rand erlaubt es zudem, in Teilgebieten oder im Masterindex nach Themen zu suchen. Die gegebenen Informationen sind knapp und präzise gehalten.

Eine Weiterentwicklung dieses Ansatzes zeigt sich beim Hilfesystem des Microsoft Internet Explorer 4.0. Dieses beachtet strenger Caroll's Guidelines, indem es sich zunächst auf die für die Lösung des Problemes wesentliche Aspekte beschränkt, und dann, für den interessierten Anwender, auf Wunsch noch detailiertere Informationen bietet.
Der Leser kann sich auch einen Index anzeigen lassen und dort gezielt nach weiteren Informationen suchen. Das Hilfesystem des Microsoft Internet Explorer 4.0 bietet zudem die Möglichkeit von dort direkt in das Internet einzusteigen. Dort kann auf einen umfassenderen Datenbestand zugegriffen werden.

Microsoft Internet Explorer 4.0

Das Hilfesystem des Netscape Communicator 4.05 geht noch einen Schritt weiter, wie die folgende Abbildung zeigt, indem es dem Anwender einen Anhaltspunkt gibt, wo sich die betreffende Funktion auf dem Bildschirm befindet.

Netscape Communicator 4.05

Neben den Informationen die der Anwender zur Lösung benötigt, werden ihm auch Details angeboten. Im Gegensatz zum JBuilder findet er auch weiterführende Themen unter dem Punkt: "Siehe auch..". Hier werden die bereits weiter oben beschriebenen Verweise (links) unter den Themen realisiert. Dies hat schon Ähnlichkeit mit einer Dokumentationsstruktur.

Allerdings wird ein wichtiges Problem, welches Caroll in seinen Guidelines angesprochen hat, (noch) nicht berücksichtigt:
Wenn der Anwender eine der Anweisungen falsch verstanden, und einen Fehler begangen hat, so wird ihm auch bei diesen modernen Tutorien keine Hilfestellung zur Fehlerbehebung angeboten. Hat er beispielsweise eine Funktion aufgerufen, die eine bestimmte Bearbeitung startet, die jedoch unerwünscht war, fehlt oft der Hinweis, wie man diese rückgängig machen kann. Caroll spricht hier von einem fehlenden ERROR RECOVERY.

1.4 Mustergestützte Softwaredokumentation

Der Arbeitstitel dieser Seminararbeit lautet Mustergestützte Softwaredokumentation. In der englischsprachigen Literatur findet man dafür oft den Ausdruck Pattern oriented Softwaredocumentation. Doch bislang war nur von den sogenannten Guidelines eines John M. Caroll die Rede. Nun aber soll der Einsatz von Mustern in der Softwaredokumentation zur Rede kommen. Wie bereits angedeutet hat die Methode der Minimalist Documentation bereits eine gewisse Struktur. Vielleicht läßt sich in dieser Struktur ein Muster erkennen.

1.4.1 Was ist ein Muster?

Christopher Alexander, ein Architekt, entwickelte 1977 die Idee einer "Mustersprache", um es quasi jedermann zu ermöglichen, sein eigenes Haus oder seine eigene Stadt zu entwerfen. [Alexander77] Er führte eine Notationsform für seine "Muster" ein. Daraus entstand eine Mustersprache (engl. Pattern Language). Eine Mustersprache ist ein Satz von Mustern, von denen jedes einzelne beschreibt, wie eine bestimmte Klasse von Problemen gelöst werden kann. Besonderes Augenmerk wird dabei auf die Berücksichtigung des Kontextes gelegt, in dem die Problemklasse liegt. Seine Mustersprache startete auf einem sehr abstrakten Niveau, erklärte wie sich die Welt in Nationen aufteilt, die Nationen sich wiederum in kleinere Gebiete zerlegen ließen, diese wieder in Städte, usw. bis auf eine Ebene in der sie erklärte, wie man Straßen, Parkplätze, Einkaufscenter, Häuser etc. anordnen sollte. Die Detailierung ging so weit, daß Alexander die Anordnung von Räumen in einem Haus vorschlug oder das Material aus dem eine bestimmte Wand sein sollte.
Diese Mustersprache war für Nicht-Architekten gedacht. Man brauchte keine spezielle Ausbildung, um sie zu benutzen; Sie hatte einen intuitiven Charakter.
In der Softwaretechnik treten ebenfalls häufig wiederkehrende Entwurfsprobleme auf. Erich Gamma, Richard Helm, Ralph Johnson und John Vlissides griffen auf diese Mustersprache von Christopher Alexander zurück und adaptierten das dort vorgestellte Schema für die Softwaretechnik. [Gamma96]

Diese Mustersprache und ihre Notation ist nicht rein-formal. Sie enthält vielmehr natürlichsprachliche Elemente, um ihrem Anspruch auch Nicht-Experten zugänglich zu bleiben gerecht zu werden. Gamma et. al haben daraus eine Notationsform mit 11 Elementen entworfen, um ihre Design Patterns (deutsch: Entwurfsmuster) zu dokumentieren.

Eine andere Notationsform bieten Gerard Meszaros und Jim Doble an[Meszaros96]. Sie sprechen anstatt von 11 nur von 5 Elementen, die ein (Entwurfs-)Muster aufweisen sollte:

Pattern Name: Ein Name, anhand dessen man das Muster erkennen und auf den man sich beziehen kann. Problem: Eine Beschreibung des Problemes, oder der Problemklasse, welches es löst. Solution: Abhängig von dem Kontext, in dem das Problem auftaucht, werden verschiedene Lösungen angeboten. Context: Hier werden die Umstände, die das Problem eingrenzen und klassifizieren, näher erörtert. Forces: Um eine bestimmte Lösung herauszufinden, müssen diese Forces berücksichtigt werden, da sie Elemente enthalten, die gegen den Einsatz der einen oder anderen Lösung in einem bestimmten Kontext sprechen.

Für nähere Informationen zum Thema Entwurfsmuster (Design Patterns) sei hier auf die Pattern Homepage verwiesen.
Diese ist unter http://hillside.net/patterns/ im Internet zu finden. Auch das Literaturverzeichnis bietet zu diesem Thema noch weitere interessante Links.

1.4.2 Muster in der Dokumentation von Frameworks

Die Dokumentation eines Frameworks muß mehreren Anforderungen genügen. Diese Anforderungen werden erfüllt, indem man der Dokumentation ebenfalls eine Muster-Struktur zugrunde legt. Diese wird manchmal auch als Pattern Language bezeichnet. Ein Framework besteht zu einem großen Teil aus Mustern. Was liegt näher, als ein Framework mustergestützt zu dokumentieren?

• Muster können zum einen das Aufgabengebiet eines Frameworks beschreiben.
• Sie erlauben es auch einem unerfahrenen Anwender das Framework zu benutzen, ohne daß er wissen muß, wie das Framework im Detail funktioniert.
• Ferner bietet die mustergestützte Dokumentation detailierte Informationen zum Design eines Frameworks, so daß der Leser daraus lernen kann, eigene Frameworks zu entwickeln.

Ralph Johnson, einer der Autoren des Buches Entwurfsmuster benutzt Patterns, um das Framework "Hotdraw", einen GUI-Builder, zu dokumentieren[Johnson92]. Ein Framework stellt einen wiederverwendbaren Entwurf für Problemlösungen in einem Kontext dar. Deshalb sollte die Dokumentation zuallererst darlegen, für welches Aufgabengebiet sich das Framework eignet. Stellt sich das Framework als unbrauchbar heraus, so muß der Anwender nicht erst viel Dokumentation lesen, um dies herauszufinden.

Hilfreich kann diese Methode insbesondere dann sein, wenn ein Entwickler von allen in dem Unternehmen eingesetzten Frameworks diesen Dokumentationsabschnitt kennt, und aufgrund dessen entscheiden kann, welches das richtige Framework für die aktuelle Aufgabe ist.

Als nächstes sollte die Dokumentation eines Frameworks darstellen, wie man mit Hilfe des Frameworks arbeiten kann. Die meisten Anwender sind nicht an Details interessiert, sondern wollen schnell und effektiv zu einer Lösung ihres Problems gelangen.(vgl. auch Guidelines von John M. Caroll). Viele Dokumentationen beschreiben zuerst, wie etwas funktioniert und kommen erst dann dazu, wie man es benutzt. Teil der Tradition von Frameworks ist aber, daß niemand ein Framework verstehen kann, solange er es nicht benutzt und damit gearbeitet hat. Die Redewendung "Learning by doing" hat sicherlich ihre Daseinsberechtigung.

Johnson wählt eine mustergestützte Dokumentation des Frameworks "Hotdraw". Dies sieht wie folgt aus. Ein Beispiel:

Pattern 4: Complex Figures Some figures have a visual presentation with internal structure. For example, they may have attributes that are displayed by other figures. It should be possible to compose them from simpler figures. Complicated figures like PERTEvent can be thought of as being composed of simpler figures. For example, a PERTEvent has a RectangleFigure and several TextFigures for the title, the duration, and the ending date. Complex figures like PERTEvent are subclasses of CompositeFigure. A CompositeFigure is a figure with other figures as components, and it displays itself by displaying its components. It has a bounding box that is independent of the bounding box of its components, and it will display its components only if they are inside of its bounding box. The selection tool and text tool will operation on its components when the left shift key is pressed. Custom tools can operate directly on the components, if you want. ... Complex figures should be a subclass of CompositeFigure, and figures that display one of its aspects should be a component of it. To enforce constraints between the components of a complex figure, see Constraints(5)[Johnson92]

Gefolgt von dem Zweck des Pattern, werden Anweisungen gegeben, wie und warum bestimmte Handlungen zum Ziel führen. Dieses wird nochmals in einer kurzen und einprägsamen Weise zusammengefaßt. Schließlich folgt ein Abschnitt, der auf verwandte Patterns verweist.

Die Theorie, wie man ein Framework entwirft, gehört nach der Meinung von Ralph Johnson an das Ende einer Frameworkdokumentation. Diese Informationen sind für denjenigen gedacht der sich intensiv mit dem Framework beschäftigen möchte, und weniger für denjenigen, der nur damit arbeitet.

Informationen über den Klassenaufbau und die Klassenstruktur lassen sich ebenfalls mit Patterns, genauer Design Patterns, dokumentieren. Wie dies geschieht, kann man in [Gamma96] nachlesen.

Ein Student von Ralph Johnson, Ian Chai, setzt ebenfalls auf eine mustergestützte Dokumentation von Frameworks. In seiner Arbeit Visuallessons dokumentiert er das Framework Visual Works von ParcPlace-Digitalk unter besonderer Berücksichtigung der Guidelines von John M. Caroll. [Guidelines]
Seine Experimente an Studenten, die Visuallessons einsetzten, haben gezeigt, daß ein hypertextbasiertes Tutorium wesentlich effektiver ist, als ein klassisches Papier-Tutorium. Die Gründe dafür liegen, wie bereits weiter oben erwähnt in der Unterstützung menschlicher Lerntechniken. Eine grobe Gliederung seines Ansatzes bei Visuallessons findet man in der untenstehenden Abbildung.

Visuallessons von Ian Chai

Wie man sehen kann, geht Chai besonders auf die Bedeutung von Beispielen ein, da er ihnen, ebenso wie Johnson einen großen Stellenwert gibt. Außerdem gibt er Hintergrundinformationen, damit der Anwender weiß, warum er dieses Problem auf diese Weise lösen kann. Ebenso wie schon beim Netscape Communicator Hilfesystem, wird ein See Next.. Abschnitt angeboten, in dem auf verwandte Themen verweist wird.

Auch hier taucht der Begriff "Pattern" immer wieder auf. Chai geht sogar so weit, daß er Pattern auf folgende Weise definiert:

Patterns are a documentation technique have been used to document good object-oriented design practices, software packages and frameworks as well as how to do many other things.

Besonders über den unterstrichenen Teil kann man unterschiedlicher Meinung sein. Patterns sind meiner Meinung nach nicht nur einfach "Muster". Sie haben mehr Ähnlichkeit mit Design Patterns [Definition], da sie kontextbezogene Problem-Lösungspaare darstellen. Wie der Screenshot jedoch zeigt, verwendet Ian Chai den Begriff Pattern auch in seiner Tutoriumstechnik Visuallessons.
Nach meinem Verständnis handelt es sich dabei jedoch nur um ein Tutorium, welches zwar eine bestimmte verlinkte Struktur aufweist und weitgehend die Guidelines von John M. Caroll berücksichtigt.
Als ich den Autor Ian Chai mit meiner Auffassung konfrontierte, bekam ich zur Antwort, daß Ralph Johnson seine Arbeit gelesen habe und mit ihm darin übereinstimme, daß es sich dabei um Patterns handle.
Am besten man einigt sich auf den Begriff "Dokumentationsmuster" für diese Klasse von Mustern.

1.5 Ausblick

Kritisch anzumerken bleibt die Tatsache, daß bislang nur GUI-Builder auf diese Weise mustergestützt dokumentiert wurden. Für andere Frameworks findet man diese Art der Dokumentation, die sich geradezu anbietet leider noch nicht. Die Frage ist nur, warum bislang nur die kleine Gruppe von GUI-Buildern so dokumentiert werden.

Auch auf anderen Gebieten kommen mustergestützte Dokumentationsverfahren zum Einsatz:
Sogenannte "Organizational Patterns [Coplien97]" zeigen einen Weg auf, wie das Entwicklungsteam organisiert sein sollte, um eine hohe Effektivität zu erreichen.

Hypertext ist ebenfalls eine Programmiersprache. Ebenso wie für Frameworks oder Organisationsfragen werden auch Mustersprachen für HTML entwickelt. Als Quelle sei hier auf Robert Orenstein verwiesen.
Der Einsatz von Hypertext ist jedoch nicht nur sinnvoll, um Tutorien zu gestalten, sondern auch zur Dokumentation von Sourcecode ist Hypertext hilfreich. "Gereifte" Softwaresysteme unterliegen, wie man auch an den Beispielen gesehen hat, ständiger Weiterentwicklung und Wartung. Um diese überhaupt effektiv und möglich zu machen, ist eine System-Dokumentation unverzichtbar.Damit kommen wir zum 2. Kapitel, welches sich mit dem Thema System-Dokumentation beschäftigt.