Dokumentversion: 1.1 (16.August 2000)
(Da sich diese Version ab Punkt 2.2.2 umfangreich von v1.0 unterscheidet,
wurde ein komplett neues Dokument erstellt.)
Autor:
Erstautor: U.Sacklowski, Fortschreibung durch projekt98, projekt99
Zustand: in Bearbeitung
Diese Dokumentation ist bei Bedarf/Erkenntnis durch die Projektmitglieder
fortzuschreiben (mit Autorenhinweis).
An dieser Stelle werden Hinweise zu den Bezugsdokumenten und den Dokumenten gegeben, die innerhalb der jeweiligen Gesamtdokumentation zu erstellen sind.
Inhalt
1. Allgemeine Bezugsdokumente
1.1 Bilder und Fenster
1.2 Detail-Überblick
1.3 Weitere Dokumente
2. Gesamtdokumentation zu den use-cases
2.1 Gesamtvorgang
2.2 Pflichtenheft
2.2.1 Pflichtenheft für eine Weiterentwicklung
2.2.2 Pflichtenheft für das vorhandene System
2.3 Design
2.4 Implementation
1. Allgemeine Bezugsdokumente
Zahlreiche Dokumente sind inzwischen auf unseren Web-Seiten vorhanden. Auf sie sollte man sich beziehen und sie bei Bedarf auch erweitern (jeder hat Schreibzugriff). Evtl. bei entsprechenden Aktivitäten die Gruppe anschließend über Email informieren.
1.1 Bilder und Fenster
Bilder und Fenster sind zu finden unter IX. Entwicklerdokumentation;
Pflichtenheft:
- Bilder,
- Fenster-Übersicht.
Wenn möglich, sollten alle Bilder und Fenster, die Teil der Dokumentation
sind, hier geführt werden.
1.2 Detail-Überblick
Unter I. Überblick; Detail-Überblick ist ein umfangreiches Dokument verfügbar, auf das man sich, insbesondere bspw. bei den physikalischen und technischen Grundlagen, beziehen sollte. Inhalt des Dokumentes:
1. Einleitung
2. Grundlagen
2.1 Physikalische Grundlagen
2.2 Technische Grundlagen
3. Meßplatz
3.1 Topographie
3.2 Diffraktometrie und Reflektometrie
3.3 Basisaufgaben
3.4 Vorgänge (Szenarien)
4. Software
4.1 Ausgangssystem
4.2 Zielsystem
4.3 Reengineering
1.3 Weitere Dokumente
Weitere Dokumente, auf die man sich beziehen kann sind bspw.:
- Use-Case-Diagramme (IX. Entwicklerdokumentation; Pflichtenheft)
- Initialisierungsdatei (.ini) (IX. Entwicklerdokumentation;
Design)
- Makrodateien (IX. Entwicklerdokumentation; Design)
- ... ?
2. Gesamtdokumentation zu den use-cases
Für Gliederungen zu den einzelnen Entwicklungsphasen, hier je use-case, geben die Literatur und die Dokumentation von Case-Tools zahlreiche Hinweise. Eine 1 : 1 - Übernahme ist aus folgenden Gründen problematisch:
- Wir entwickeln nicht, sondern erarbeiten die Entwicklerdokumente im
Nachhinein (Reverse Engineering).
- Einzelne Erweiterungen, wie bspw. der 2-dim. CCD, sind relativ klein,
womit vorhandene Gliederungen überdimensioniert erscheinen.
Daher ist jeder von uns gefragt, die nachfolgenden Empfehlungen auf seine Belange zu transformieren.
2.1 Gesamtvorgang
Die Dokumentation des Gesamtvorganges ist für komplexe Abläufe, wie sie bei der Topographie und der Diffraktometrie/Reflektometrie anzutreffen sind, sinnvoll. Innerhalb der Softwareentwicklung gehört ein solches Dokument in die Analysephase, hier als Teil des Ist-Zustandes und des Soll-Konzeptes. (Die Analysephase ist der Anforderungsdefinition mit dem Dokument 'Pflichtenheft' vorgelagert.)
Als Beispiel für ein Gesamtvorgang-Dokument sei verwiesen
auf:
- Topographie-Gesamtvorgang (IX. Entwicklerdokumentation;
Gesamtdokumentation; Topographie).
Inhalt dieses Dokumentes:
1. Einleitung: Fachlicher Hintergrund,
Ziel und Grobablauf des Topographie-Gesamtvorganges
2. Feinablauf des Topographie-Gesamtvorganges
2.1 Verbale Beschreibung
(eine weitere Untergliederung erfolgt dort)
2.2 Beschreibung in Pseudokode
Bemerkungen zu diesem Dokument:
Der Gesamtvorgang wird in Teilvorgänge gegliedert. Ihrer Realisierung
dienen:
- Manuelle Aufgaben, d.h. Aufgaben ohne Unterstützung des RTK-Steuerprogrammes
(z.B. handschriftlicher Eintrag in das Protokollbuch),
- Dialog-Aufgaben, d.h. Aufgaben mit Unterstützung des RTK-Steuerprogrammes
(z.B. bei der manuellen Justage, wo sich Eingaben in eine Dialogbox durch
den Nutzer mit der durch das RTK-Steuerprogramm gesteuerten Regelung abwechseln).
Dialogaufgaben stellen Anforderungen an das RTK-Steuerprogramm dar. Es sind use-cases und sie sind im Pflichtenheft weiter zu spezifizieren.
Die Beschreibung des Feinablaufes des Topographie-Gesamtvorganges erfolgt einmal verbal, hier ausführlich und im Falle von Dialogaufgaben mit den entsprechenden Dialogboxen und Dialogfenstern, und zum anderen in Pseudocode. Letztere Darstellung ist kompakt und soll den Zugang zum Ablauf des Gesamtvorganges erleichtern. (Dieser Vorschlag stammt von eine Gruppe aus dem Projekt99-Seminar. Seine Zweckmäßigkeit bleibt zu diskutieren.)
Zum Pseudocode:
Verwendete Konstrukte: (nach R.Dumke: Modernes Software Engineering,
Vieweg 1993, S.15)
| Sequenz
A seq
|
Selektion
A
|
Iteration
A
|
Iteration
A
|
zusätzlich: || Parallelität
Wörter einer lexikalischen Einheit werden mit '_' oder '-' verbunden
kursiv-fett: use_case
kursiv: Titel von DB und DF
DB: Dialogbox
DF: Dialogfenster
MA: Manuelle Aufgabe
DA: Dialog-Aufgabe
Bsp. zum Pseudocode aus dem Topographie-Dokument:
Topographie_Gesamtvorgang seq
Erfassung_allgemeiner_Angaben_zum_Meßvorgang
seq
Handschriftliche_Einträge_in_einem_Protokollbuch
(MA)
Allgemeine_Einstellungen_zum_Meßvorgang
(DA)
/* DB: Allgemeine
Einstellungen */
Erfassung_allgemeiner_Angaben_zum_Meßvorgang
end
Platzierung_der_Probe_auf_dem_Probenteller_und_Vorabjustage
seq
.....
2.2 Pflichtenheft
Wir orientieren uns an der von Balzert empfohlenen Gliederung (H. Balzert: Lehrbuch der Softwaretechnik: Softwareentwicklung; Berlin, Oxford: Spektrum, Akad. Verlag, 1996, S. 106 f). Dortige Gliederung ist recht ausführlich, entsprechende kritische Hinweise wurden in Pkt. 2 Anfang geäußert.
Empfehlung für den Fall der Dokumentation
- einer Weiterentwicklung,
- des vorhandenen Systems.
2.2.1 Pflichtenheft für eine Weiterentwicklung
Hierfür eignet sich die Vorgabe von Balzert. Sebastian Lühnsdorf und Alexander Schad sind in Ihrem Pflichtenheft zur 'Einbindung 2-dimensionaler Detektoren in das RTK-Steureprogramm' so verfahren (siehe: IX. Entwicklerdokumente, Gesamtdokumentation, Detektoren, 2-dimensionale Detektoren). Ob die Gliederung überdimensioniert ist, ist Geschmackssache.
2.2.2 Pflichtenheft für das vorhandene System
Hierfür ist die Balzertsche Gliederung stark zu reduzieren.
Als Bezugsbeispiele können zum einen die beiden neuen Pflichtenheft-Dokumente
zur Topographie genommen werden und zum anderen das Pflichtenheft zur 'Manuellen
Justage'. Siehe:
- IX. Entwicklerdokumente, Gesamtdokumentation, Topographie, Einst.
der Parameter für die Topographie (neue Version),
- IX. Entwicklerdokumente, Gesamtdokumentation, Topographie, Start
und Kontrolle der Topographie (neue Version),
- IX. Entwicklerdokumente, Gesamtdokumentation, Man./Autom. Justage,
Probe u. Kollim. manuell einstellen (K. Bothe).
Weiterer Bezug: Einstellen der Parameter für die Topographie (neue Version):
a) Dokumentationskopf
--> siehe dort
b) Gliederung
1. Überblick
2. Funktionale Beschreibung
2.1 Topographie mit Einfachbelichtung
2.2 Topographie mit Mehrfachbelichtung
2.3 Arbeitspunkt spezifizieren
2.4 Abnormale Ausnahmebehandlung
2.5 Start und Beendigung der Teilfunktion
3. Benutzerschnittstelle
3.1 Dialogbox 'Einstellungen Topographie'
3.1.1 Steuerung
3.1.2 Eingaben/Ausgaben und Prüfung
4. Daten
4.1 .ini-Datei
4.2 ... z.B. .mak-, Log- und Messwert-Datei
5. Testfälle
6. Fehler und Änderungswünsche
6.1 Fehler aus Nutzersicht
6.2 Änderungswünsche
7. Offene Fragen
Allgemeine Bemerkungen zur Gliederung:
Vorabhinweis: In diesem Beispiel gibt es nur eine Dialogbox (Pkt. 3.1), die im Pkt. 2 funktional beschrieben wird. Im Falle mehrerer Dialogboxen/Dialogfenster sind die Punkte 2 und 3 entsprechend zu gliedern.
Sonstige Bemerkungen:
2. Funktionale Beschreibung
Hier sind Redundanzen mit der entsprechenden Dialogaufgabe des Gesamtvorganges
gegeben. Die Beschreibung hier sollte detaillierter erfolgen. Wichtig ist,
daß Konsistenz gewahrt wird, d.h., die Teilfunktionen sollten dort
wie hier die gleichen sein.
Des weiteren dient das Voranstellen der/des entsprechenden Dialogbox/Dialogfensters dem Verständins der funktionalen Beschreibung.
3. Benutzerschnittstelle:
Zu beschreiben ist die grafische Ein/Ausgabe (Dialogboxen, Fenster
zur Anzeige von Meßergabnissen
(StepScan, AreaScan).
3.1.2 Eingaben/Ausgaben und Prüfung
Zu jedem Dialogelement sind anzugeben:
5. Testfälle
Hier sind umfassende Testfälle zu spezifizieren, wie Kombinationen
von Eingabewerten und die Reaktion darauf beim OK- und Abbrechen-Button.
Des weiteren ist zu testen, ob die Werte in das .ini-File übernommen
werden.
Zur Dokumentation aller Testfälle (deckend) und einer getroffenen Auswahl sollte der CTE benutzt werden.
6. Fehler und Änderungswünsche
Bei den Fehlern sind nur solche aus Nutzersicht zu dokumentieren. Fehler
aus Entwicklersicht werden im Web-Dokument 'Pflichtenheft, Systemfehler,
Systemfehler aus Entwicklersicht, Topographie' beschrieben.
7. Offene Fragen
???
(Beispiele hierfür siehe: Pflichtenheft zur 'Probe und Kollimator
manuell einstellen'.)
Bezug: Probe und Kollimator manuell einstellen (K. Bothe):
Wie schon in obigem Bezug innerhalb des Punktes 7, so sind auch in anderem Zusammenhang Anregungen diesem Dokument zu entnehmen.
2.3 Design
Einiges hierzu siehe: IX. Entwicklerdokumente, Design
Klassendiagramm (Ist-Zustand):
- Klassendiagramm in UML
- verbale Beschreibung der Attribute und der Wirkung der Methoden
- Bewertung der vorhandenen Klassenstruktur
2.4 Implementation
Einiges hierzu siehe: IX. Entwicklerdokumente, Implementation