In diesem Kapitel steht die Form der Dokumentation im
Vordergrund. Dazu untersuche ich die Struktur der Dokumente des
Entwurfs und ermittle die daraus die notwendigen Links zwischen
den einzelnen Teilen der Dokumentation. Danach folgt eine
Beschreibung der Bildschirmaufteilung und eine Aufteilung der
Links. Im nächsten Abschnitt behandle ich den Aufbau des
Glossar. Als nächstes wird eine Notationserweiterung für die
Diagramme vorgeschlagen. Zuletzt folgt noch ein Darstellung der
Abschnitte in der Dokumentation, die für die Nachdokumentation
des Framework OSEFA notwendig waren..
Bei dem Entwurf eines Programmes entstehen viele Dokumente.
Bei der Dokumentation ist darauf zu achten, daß diese Dokumente
verfügbar sind. Dabei muß jedoch eine Struktur gefunden werden,
mit welcher der Leser den Programmaufbau leicht verstehen kann
und schnell das Dokument mit der gewünschten Informationen
findet. Sind die Dokumente unstrukturiert, müßte der Leser alle
Dokumente durchlesen und wahrscheinlich wäre das Verständnis
für den Programmaufbau nicht sehr groß.
Für die Einarbeitung in den Aufbau des Dokumentes bieten sich
die Ergebnisse der Analyse an. Sie zeigen einerseits die
wesentlichen Teile des Programmaufbaus, andererseits ist die
Darstellung dieser Informationen nicht durch zusätzliche Klassen
zu komplex. Von den Analyseergebnissen kann man dann auch schnell
zu den Details, wie zum Beispiel der Beschreibung einer Klasse,
gelangen.
Abbildung 18: Struktur der
Dokumentation des Entwurfs
Aus diesem Grund werden dem Leser, wie in Abbildung 18
dargestellt, mehrere Möglichkeiten zum Einstieg in die
Dokumentation angeboten:
- die Klassendiagramme,
- die Use Cases
- und die Hot Spots
Das zuerst angezeigte Klassendiagramm dient nur
für einen Überblick mit den wichtigsten Klassen und ihren
Beziehungen, wie sie während des Entwurfs entstehen. Der Leser
kann von diesem Diagramm weitere Diagramme erreichen, in diesen
Diagrammen werden jeweils Ausschnitte aus dem Überblicksdiagramm
verfeinert und durch weitere Klassen ergänzt.
Der Einstieg über die Hot Spots ist nur für Frameworks
vorgesehen. Bei Frameworks kann man davon ausgehen, daß ein
großer Teil der Leser der Dokumentation des Entwurfs schon mit
dem Framework gearbeitet hat und eigene Programme mit Hilfe der
Konfiguration des Frameworks erstellt hat. Das Wissen daraus kann
bei Benutzung der Hot Spots als Einstieg in die Dokumentation die
Einarbeitungszeit verkürzen.
Eine weitere Hilfe beim Verständnis in den Programmaufbau soll
die Nutzung von den Entwurfsmustern als Teil der Dokumentation
sein. Ein Leser, der die Entwurfsmuster kennt, kann viel
schneller die Beziehungen zwischen den Klassen verstehen. Aus
diesem Grund sind die Entwurfsmuster in den Klassendiagrammen
markiert. Zusätzlich werden die Entscheidungen bei der Auswahl
und der Nutzung des Entwurfsmusters als eigener Teil in die
Dokumentation eingefügt.
Neben der Verbindung zwischen den Dokumenten müssen auch
Verbindungen zwischen den Versionen der Dokumente vorhanden sein.
Da Software häufigen Änderungen unterliegt, müssen diese
Änderungen auch in der Dokumentation enthalten sein. Aus diesem
Grund muß zu jedem Dokument ein Versionsbaum entstehen, der die
Veränderungen in dem Dokument im Lauf der Zeit dokumentiert. Bei
der von mir erstellten Dokumentation sollten die Änderungen
gegenüber der vorherigen Version in den Texten mit Hilfe von
Farben markiert werden, damit der Leser schneller die Änderungen
erkennen kann. Dabei sind drei Farben genutzt worden, jeweils
eine Farbe für unveränderten Text, für veränderten Text und
für neuen zusätzlichen Text. Bei Entwurfsmustern wird kein
Versionsbaum erstellt, sondern die lineare Entwicklung von der
Auswahl der Muster bis zur technischen Realisierung des Musters
in vier Schritten dokumentiert, vgl. Abschnitt 2.1.2 .
Die dargestellten Informationen müssen geeignet strukturiert
werden, damit sich der Leser zurechtfindet. Durch die komplexen
Strukturen innerhalb eines Hypertext kann es leicht passieren,
daß der Leser die falschen auswählt und keinen Weg zurück zu
den gewünschten Informationen findet. Der Leser ist dann "lost
in hyper-space" [Nielsen, 1993]. Zur Vermeidung diese
Zustand ist es notwendig, daß die Links ausreichend beschrieben
sind. Zusätzlich ist es für den Leser hilfreich, wenn er
ständig darüber informiert ist, wo er sich befindet.
Abbildung 19:
Bildschirmaufteilung
Aus diesem Grund habe ich die in Abbildung 19 dargestellte
Bildschirmaufteilung gewählt. In dem Kopfteil kann ein kurzer
Text über die Art der angezeigten Information angezeigt werden.
Dabei soll der Text aus dem Typ des Objektes, z.B.
Klassendiagramm, Entwurfsmuster oder Klasse und den konkreten
Namen des Objektes bestehen.
Im Teil Inhalt werden die eigentlichen Informationen über das
jeweilige Objekt angezeigt. Da viele Objekte, wie die Klassen und
die Entwurfsmuster, mit Text beschrieben werden, reicht der Platz
in diesem Bildschirmteil meist nicht aus um den kompletten Text
darzustellen. Darum kann in diesem Bildschirmteil gescrollt
werden.
Im Bildschirmteil für das Inhaltsverzeichnis werden Links zu
einzelnen Abschnitten im Text des Inhaltsteils angeboten. Diese
Links sollen dem Leser ein schnelles Bewegen zu den für ihn
relevanten Textteilen ermöglichen. Dies ist nötig, da der
Browser große Texte nicht immer komplett im Inhaltsteil
darstellen kann. Außerdem sollen hier Links zu weiteren
Informationen zu diesem Objekt angeboten werden. Im unteren Teil
des Bildschirms werden zusätzliche Links zur Navigation
dargestellt .
Die in Abbildung 19 dargestellte Bildschirmaufteilung reicht
jedoch nicht aus. Es fehlt die Möglichkeit auf die Links der
Objekte auf höheren Ebenen (vgl. Abbildung 18) zuzugreifen. Da
diese Objekte den Kontext der angezeigten Informationen
beschreiben, kann es für das Verständnis nötig sein diese
Dokumente zu lesen. Deshalb wurde die Bildschirmaufteilung
erweitert.
Abbildung 20:
c³-Struktur
Die in Abbildung 20 dargestellte Aufteilung des Bildschirms, mit
c³-Struktur bezeichnet, ermöglicht es dem Leser immer wichtige
Links der oberen Ebenen anzuzeigen. Bei dieser
Bildschirmaufteilung werden die für die Orientierung wichtigen
Köpfe mehrerer Ebenen gezeigt. Damit kann der Leser nicht nur
das aktuelle Objekt identifizieren, sondern auch der Kontext des
Objektes ist vorhanden. Die für die Navigation wichtigen
Bildschirmteile, Inhaltsverzeichnis und Navigation, werden
ebenfalls dargestellt. Mit Hilfe der hier dargestellten Links
kann der Leser schnell in die höheren Ebenen zurückkehren und
sich dort über den Kontext informieren. Bei einem Wechsel in
eine tiefere Ebene wird nur der Bildschirmteil Inhalt
überschrieben. Die anderen Bildschirmteile bleiben weiterhin auf
dem Bildschirm.
Damit der Leser nicht durch sehr starke Aufteilung des
Bildschirms verwirrt wird, werden den einzelnen Ebenen
unterschiedliche Hintergrundfarben zugeteilt. Damit der Kontrast
nicht zu sehr leidet, werden helle Farbtöne verwendet. Die
Systemebene ist rosa. Bis zur Ebene der Methoden und der
Attribute, die türkis ist, wird die Farbe immer kälter, so daß
ein Tiefeneindruck entsteht.
Der wesentliche Vorteil einer Dokumentation mit Hypertext
gegenüber einer Dokumentation auf Papier ist, daß mit Hypertext
sich komplexere Dokumentstrukturen aufbauen lassen. Ein
sequentieller Text kann durch eine Gliederung allenfalls eine
baumartige Struktur bekommen. Ein Hypertext kann durch Links eine
beliebige Struktur besitzen.
Deshalb stellt sich die Frage, wo und welche Links in der
Dokumentation sein sollen, die die Dokumentenstruktur
widerspiegeln. In der Bildschirmaufteilung im Abschnitt 3.2.2
wurden zwei Bildschirmteile (Inhaltsverzeichnis und Navigation)
für die Links vorgesehen.
Das Inhaltsverzeichnis nimmt unterschiedliche Typen von Links
auf. Zum einen sind dort Links zu den einzelnen Abschnitten im
Text. Da bei einem Wechsel in eine tiefere Ebene der Inhalt zu
diesem Objekt überschrieben wird, ist auch ein Link vorhanden,
der den Rücksprung zu dieser Ebene ermöglicht. Dieser Link
überschreibt dann alle Informationen der unteren Ebenen und
schreibt den Inhalt in den entsprechenden Bildschirmteil.
Im Inhaltsverzeichnis sind zusätzlich Links zu weiter
beschreibenden Grafiken, dies können Klassendiagramme,
Interaktionsdiagramme oder Zustandsdiagramme sein. Diese Grafiken
werden nicht direkt in den Inhalt geschrieben, weil diese
Grafiken meist sehr groß sind und deshalb viel Platz auf dem
Bildschirm beanspruchen. Kleinere Grafiken können auch direkt in
den Text eingefügt werden. Weitere Links im Inhaltsverzeichnis
führen zu den Testfällen und den darunter liegenden Ebenen. So
sind zum Beispiel bei den Entwurfsmustern Links zu allen Klassen
aufgeführt, die im Muster enthalten sind.
Der zweite Bildschirmteil, der Platz für Links enthält, ist die
Navigationsleiste. Sie nimmt die Kontext bezogenen Links auf.
Dies sind zum Beispiel Links zu anderen Objekten der gleichen
Ebene. So sind bei den Klassen Links zu anderen Klassen des
gleichen Entwurfsmusters vorhanden. Diese Links dienen dem
Verständnis des Zusammenwirkens der Klassen. Dies ist vor allen
bei Klassen sinnvoll, die in unterschiedlichen Mustern mit
unterschiedlichen Rollen auftreten. Denn hier wird ja im
umgebenen Rahmen der c³-Struktur nur ein Entwurfsmuster
dargestellt. Mit den hier angebotenen Links kann man auch das
Zusammenwirken der Klasse mit den Klassen des anderen
Entwurfsmusters zum Ausdruck bringen. Zusammen mit diesen Links
ist auch ein Link zu dem Entwurfsmuster vorhanden. Damit kann man
sich auch dort über den Kontext der Klasse im Entwurfsmuster
informieren. Auf den anderen Ebenen der Dokumentation sind
ähnliche Links vorhanden, die sich auf den dortigen Kontext
beziehen. Bei den Entwurfmustern ist zum Beispiel ein Verweis auf
den Hot Spot und ein Verweis zu dem Originalmuster nach [Gamma et
al., 1995] vorhanden.
Hier sind auch Links zu den anderen Versionen eines Objektes. Da
bei der Softwareentwicklung immer wieder Änderungen am Entwurf
vorgenommen werden, entstehen auch Dokumente für
unterschiedliche Versionen des Objektes. Da diese zum Teil für
das Verständnis über den Entwurf wichtig sein können, sind
diese alten Dokumente von hier aus erreichbar.
Zusätzlich sind in diesem Bildschirmteil weitere Links mit
speziellen Funktionen, so ist hier ein Link für den Rücksprung
zur zuletzt angezeigten Seite. Wobei diese Links auf eine Ebene
bezogen sind. Das heißt, daß der Link auf der Systemebene die
letzte Seite auf der Systemebene wieder anzeigt und für die
anderen Ebenen entsprechend. Hier sind auch weitere Links, wie
die Links zur Erklärung der Notation der Grafiken.
In dem eigentlichen Inhalt sind ebenfalls Links. Besonders bei
grafischen Beschreibungen ist es sinnvoll, direkt aus der Grafik
zu den gewünschten Dokumenten zu springen. Dies sind neben den
Klassen auch die Hot Spots und die Entwurfsmuster, die durch eine
Notationserweiterung in den Grafiken sichtbar sind.
Bei Beschreibungen mit Text können ebenfalls zusätzliche Links
im Bildschirmteil Inhalt sinnvoll sein. Wenn im Text eine
Aufzählung vorkommt, so sollten von dort aus direkt Links zu den
Beschreibungen der einzelnen Elementen der Aufzählung vorhanden
sein. Dies erleichtert das Lesen der Dokumentation, da dann die
Links nicht mehr im Inhaltsverzeichnis gesucht werden müssen.
Allerdings müssen diese Begriffe auch im Inhaltsverzeichnis
vorhanden sein, damit ein Leser, der sich gut in der
Dokumentation auskennt, schnell zu den gewünschten Informationen
kommt.
Im Fließtext können auch Links vorkommen. Im Text vorkommende
Begriffe sollten erklärt werden, wenn dies nötig ist. Diese
Erklärung kann im Glossar erfolgen. In diesem Fall muß ein Link
in das Glossar vorhanden sein. Das gleiche gilt bei der
Erwähnung von Literatur, bei der ein Link in das
Literaturverzeichnis vorhanden sein muß. Werden Begriffe aus
darunterliegenden Ebenen in dem Text erwähnt, so muß auch von
hier ein direkter Link vorhanden sein. So werden zum Beispiel in
den Entwurfsmustern häufig die beteiligten Klassen erwähnt. Es
kann vorkommen, daß die Begriffe an unterschiedlichen Stellen
erklärt werden, z.B. weil für einen Begriff ein Eintrag im
Glossar steht und gleichzeitig dieser Begriff der Name einer
Klasse ist. In diesem Fall sollen beide Links erzeugt werden,
wobei der Link zur Klasse durch "[class]"
markiert wird, damit der Leser die beiden Links unterscheiden
kann. Die Erweiterung mit dem zusätzlichen Link zur Klasse soll
nur an Stellen eingefügt werden, wo dies sinnvoll ist, z.B. bei
den Entwurfsmustern.
Durch die Erklärung von Begriffen im Glossar kann das
Verständnis der Dokumentation wesentlich erleichtert werden.
Denn für einen Leser ohne Erfahrung mit dem Entwurf des
Programmes stehen im Glossar die nötigen weiteren Erklärungen
zur Verfügung. Der erfahrene Leser jedoch wird nicht durch für
ihn unnötige Informationen gestört, da diese ihm schon bekannt
sind.
Damit ein Glossar nützlich ist, muß der Zugriff auf die
Begriffserklärungen einfach sein. Die Nutzung von HTML
erleichtert den Zugriff auf diese Begriffe, weil hier Links zu
den Erklärungen direkt in den Text eingefügt werden können.
Dem Leser wird gegenüber gedruckten Dokumentationen das
Blättern erspart. Dafür muß jedoch bei jedem Auftreten des
Begriffs ein Link eingefügt werden. Die Effektivität des
Glossars läßt sich noch weiter erhöhen, wenn bei der
Erklärung eines Begriffs im Glossar diese Erklärung den Text,
in dem der Begriff steht, nicht überdeckt. Denn dann kann der
Leser beide Texte gleichzeitig lesen und so den Text schneller
verstehen. Dafür ist es jedoch notwendig, daß der Bildschirm
groß genug ist, um beide Texte gleichzeitig darzustellen.
Die erklärten Begriffe sollten nicht nur über den Text
erreichbar sein, es muß auch eine alphabetische Liste aller
Begriffe vorhanden sein. Diese Liste muß weiter unterteilt
werden, wenn die Liste zu lang wird, was schnell vorkommt, da
meist viele Begriffe erklärt werden müssen.
Bei der Erklärung eines Begriffes sollte auch die Entwicklung
des Begriffes in der Programmentwicklung berücksichtigt werden.
Meist werden die Begriffe in der Analysephase entdeckt und dort
definiert. Im weiteren Verlauf der Entwicklung kann sich die
Definition des Begriffs verändern. Eine Veränderung der
Definition kann zum Beispiel durch eine Korrektur von
Unklarheiten während der Analyse notwendig sein. Diese
Veränderungen sollten auch festgehalten werden. Ist die
Veränderung nur eine Ergänzung der Definition, kann dies durch
einfaches Anhängen an die alte Definition erfolgen. Wird der
Begriff komplett neu definiert, so sollte die alte Definition
auch weiterhin lesbar sein. Es ist natürlich kenntlich zu
machen, daß diese Definition veraltet ist. Dieses Festhalten der
Entwicklung eines Begriffes kann das Verstehen dieses Begriffes
wesentlich erleichtern. Gerade wenn der Begriff wegen
Unklarheiten komplett neu definiert wird, hilft es dem Leser,
wenn er erkennt, welche Definition falsch ist. Ohne dieses
Festhalten kann es sein, daß der Leser zuerst den Begriff
ebenfalls falsch versteht. Das Festhalten von alten Definitionen
eines Begriffes ist auch nötig, wenn sich die Definition
zwischen zwei Versionen ändert. Liest jemand die Dokumentation
der alten Version, so muß er Zugriff auf die alte Definition
haben.
Abbildung 21:
Entwicklung eines Begriffs
Neben den Änderungen der Definition von Begriffen können sich
Begriffe auch anders verändern, wie in Abbildung 21 dargestellt.
Diese Veränderungen gleichen den Entwicklungen der Klassen. Ein
Begriff kann verfeinert und aggregiert werden. Bei der
Verfeinerung wird ein Begriff in mehrere andere Begriffe
aufgeteilt, zum Beispiel gibt es in dem Framework OSEFA den
Begriff Ablaufsteuerung. Dieser Begriff teilt sich in Grob- und
Feinsteuerung auf. Diese zwei Begriffe zusammen ergeben die
Ablaufsteuerung. Ein Begriff kann auch aggregiert werden. Die
neuen Begriffe sind dann Teile des alten Begriffs. Diese
Beziehungen müssen auch als Links in der Beschreibung der
Begriffe enthalten sein.
Die Begriffe im Glossar können einer Klasse im Programmcode
entsprechen. Das heißt, die Begriffe wurden in der Analyse
gefunden und dann beim dem Entwurf als Klasse aufgenommen. Diese
Beziehung muß als Rückverweis in die Dokumentation des Entwurfs
als Link aufgenommen werden.
Vor allem in der Analyse- und der Designphase werden bei der
Softwareentwicklung viele Diagramme, wie Klassendiagramme und
Interaktionsdiagramme, erzeugt. Diese Form der Darstellung
erleichtert das Verständnis für die Software. Deshalb sollte
die Dokumentation diese Diagramme auch enthalten. Die Diagramme
sollten auch in den unterschiedlichen Versionen in der
Dokumentation enthalten sein, weil die Folge von Versionen die
Entwicklung der Software verdeutlicht. Die aktuelle Version muß
natürlich immer zuerst erreichbar sein.
Diese Diagramme werden meist mit Hilfe von Entwicklungstools
erstellt. In den Klassendiagrammen dieser Entwicklungstools
fehlen jedoch wichtige Informationen. In diesen Diagrammen sind
keine Entwurfsmuster und keine Hot Spots markiert. Da diese
Informationen für das Verständnis des Programmes hilfreich sein
können, müssen die Diagramme um diese Informationen ergänzt
werden.
Dazu ist eine Erweiterung der Notation notwendig, siehe Abbildung
22. Die Entwurfsmuster werden durch einen hellblauen Hintergrund
gekennzeichnet. Alle Klassen eines Musters werden hellblau
hinterlegt. Treten Überschneidungen bei den Entwurfsmustern auf,
weil einige Klassen in mehreren Entwurfsmustern enthalten sind,
so wird der Hintergrund an den entsprechenden Stellen dunkler (in
der Abbildung bei der Klasse CNC_Maschine). Die Beschriftung der
Entwurfsmuster erfolgt mit gelben Rechtecken mit schwarzer
Schrift, die am Rand des blauen Hintergrunds plaziert werden. Es
wird der Name des Entwurfsmusters und eine Bezeichnung für die
Aufgabe des Entwurfsmusters angegeben.
Hot Spots werden ebenfalls mit gelben Rechtecken markiert. Sie
werden in der Nähe der beteiligten Klassen plaziert. Die
Beschriftung gibt den Zweck des Hot Spots an und verdeutlicht,
daß es sich um einen Hot Spot handelt. Dabei wird als weitere
Unterscheidung zu den Entwurfsmustern eine rote Schrift
verwendet.
Damit die Diagramme in weiteren Diagrammen verfeinert werden
können, wird die Notation noch um graue Rahmen erweitert. Dieser
Rahmen gibt an, daß die Beziehungen zwischen den Klassen in
diesem Rahmen in einem weiteren Diagramm detaillierter
dargestellt werden. In den neuen Diagramm können dann auch neue
Klassen hinzugefügt werden. An dem Rahmen ist ein weißes
Rechteck mit schwarzen Rahmen und schwarzer Schrift vorhanden,
das den Namen des Diagramms angibt.
Abbildung
22: Klassendiagramm mit
Entwurfsmuster und Hot Spots, vgl. [Schmid, 1996b]
Im Rahmen der Diplomarbeit wurde das Framework OSEFA als
Beispiel genommen. Für ein Framework sind neben der
Dokumentation des Entwurfs auch andere Teile zu dokumentieren,
damit das Framework nutzbar ist. Aus diesem Grund sind in dem
Beispiel zu dem Abschnitt mit der Beschreibung des Entwurfs zwei
weitere Abschnitte vorhanden.
Ein Framework kann nicht alle Bereiche im Anwendungskontext
abdecken. Deshalb muß sich der mögliche Benutzer des Frameworks
einen schnellen Überblick über die Fähigkeiten des Frameworks
machen können. Mit diesen Informationen kann der Benutzer dann
entscheiden, ob er dieses Framework nutzen will. Diese
Informationen werden dem Benutzer im Abschnitt Einleitung zur
Verfügung gestellt. Hier werden neben der allgemeinen
Beschreibung des Frameworks OSEFA mit der Problembeschreibung,
dem Lösungskonzepts und Beispielen, auch technische
Informationen über die Einsetzbarkeit von OSEFA gegeben. Dazu
zählen die Abgrenzung des Fertigungsgebietes mit Beschreibung
der Voraussetzungen im Fertigungsablauf (Frozen Spots) und den
variablen Teilen des Frameworks (Hot Spots) [Schmid, 1996a].
Weiterhin stehen Informationen über die Portierbarkeit und die
Intregrierbarkeit von OSEFA zur Verfügung.
Der zweite zusätzliche Abschnitt, der Abschnitt Konfiguration,
besteht aus mehreren Arbeitsanleitungen. Mit Frameworks lassen
sich einfach und schnell ein neues Programm für eine bestimmte
Konfiguration erstellen. Bei Black-Box Frameworks, wie das
Framework OSEFA [Schmid, 1996b], geschieht die Anpassung nur
durch Einbinden und Parameterisieren der vorhandenen Komponenten.
Für die Anpassung von OSEFA geschieht dies, indem eine bestimmte
Funktion neu erstellt wird [Peters, 1997]. Diese Funktion dient
zur Erstellung der benötigten Komponenten aus Klassen und der
Verknüpfung von den Komponenten. Die Erstellung dieser Funktion
wird in mehreren Arbeitsanleitungen in einem Unterabschnitt des
Abschnittes Konfiguration gezeigt. In zwei weiteren
Unterabschnitten wird die Erstellung von Konfigurationsdateien
beschrieben. Diese Konfigurationsdateien dienen der
Parameteresierung von OSEFA. Wünschenswerte direkte
Querverbindungen zwischen den Hot Spots in diesem Abschnitt und
der Beschreibung des Entwurfs dieses Hot Spots sind nicht
vorhanden. Denn die mit der gegenwärtigen Werkzeugumgebung
erzeugten HTML-Seiten können die umliegenden Frames nicht
aufbauen (Konzepte zur Lösung dieses Problemes siehe Abschnitt
4.3.1).
Da diese zwei Abschnitte nicht zum eigentlichen Thema der
Diplomarbeit der Dokumentation des Entwurfs gehören, werden
diese Abschnitte nicht weiter betrachtet. Der Aufbau der beiden
Abschnitte gleicht im wesentlichen dem Abschnitt Design, den ich
in den vorherigen Abschnitten beschrieben habe.
© Technische Informatik