Dokumentversion: 1.0 (07.Juli 2000)
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.
- 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 des Dokumentes:
1. Einleitung: Fachlicher Hintergrund,
Ziel und Grobablauf des Topographie-Gesamtvorganges
2. Feinablauf des Topographie-Gesamtvorganges
2.1 Verbal (eine weitere
Untergliederung erfolgt dort)
2.2 Pseudokode
2.2.1 Syntax
2.2.2 Topographie-Gesamtvorgang
Bemerkungen:
Unterschieden wird bei der Betrachtung des Gesamtvorganges zwischen Manuellen Aufgaben und Dialog-Aufgaben. Des weiteren wird bei der Beschreibung neben der gegliederten verbalen Form die Form des Pseudocodes benutzt. Letztere Form war im Projekt99-Seminar von eine Gruppe zwecks besserem Verständnis empfohlen worden (bleibt zu diskutieren).
aus dem Dokument:
Der Feinablauf 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. Diese Darstellung ist kompakt und soll den Zugang zum Ablauf des Gesamtvorganges erleichtern.
Der Gesamtvorgang wird in Teilvorgänge gegliedert. Ihrer Realisierung
dienen:
- Manuelle Aufgaben, d.h. ohne Unterstützung des RTK-Steuerprogrammes
(z.B. handschriftlicher Eintrag in das Protokollbuch),
- Dialog-Aufgaben, d.h. 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.
... und 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
Als Bezugsbeispiel können die beiden neuen Pflichtenheft-Dokumente
zur Topographie genommen werden, ergänzt um 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).
Bezug: Einstellen der Parameter für die Topographie (neue Version):
a) Dokumentationskopf
--> siehe dort
b) Gliederung
1. Zielbestimmung
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
5. Testfälle
6. Fehler und Änderungswünsche
6.1 Fehler aus Nutzersicht
6.2 Änderungswünsche
7. Offene Fragen
Allgemeine Bemerkungen zu:
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.
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.0 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
2.4 Implementation
Einiges hierzu siehe: IX. Entwicklerdokumente, Implementation