7. Projektdokumentation Dokumentenarten Inhalte von...

Prof. Dr. Stephan KleukerSoftware-Engineering Projekt 161

7. Projektdokumentation

• Dokumentenarten

• Inhalte von Lasten- und Pflichtenheften im OO-Umeld

• Technische Dokumentation


Grundsätzliches

• Die benötigte Dokumentation hängt stark von der Projektart ab, bei externen Kunden ist Lasten- oder Pflichtenheft oft Vertragsbestandteil– Externer Kunde, großes Projekt: sehr viel

Aufwand notwendig– Öffentlicher Auftraggeber: häufig detaillierte

(nicht immer sinnvolle) Vorgaben (V-Modell)– Internes Großprojekt: ähnlich wie externer Kunde,

aber flexibler im Verlauf anpassbar– Mittleres / kleines Projekt: genau notwendige

Dokumentation suchen

• Generell Bedenken: Dokumentationserstellung kann langweilig sein, in Großprojekten als Erinnerung wichtig, für Wartung zentraler Erfolgsaspekt


Arten von Dokumenten

• Lastenheft / Pflichtenheft: zentrale Beschreibung, wa s gemacht werden soll

• Technische Dokumentation, z. B.: Designmodell, Soft ware-Architektur, Design-Entscheidungen

• QS-Handbuch: was muss wann von wem wie geprüft werden , wann ist Prüfung erfolgreich

• Werkzeughandbuch: wie, was nutzen, welche Einstellu ngen• Projektdokumentation: Projektpläne, Risikobehandlung,

Projektlogbuch• Programmdokumentation (typisch mit Dokumentengenerator

aus Quellcode)• Nutzungshandbuch / Installationshandbuch

• projektabhängig festlegen, was noch/nicht benötigt w ird


Lastenheft oder/und Pflichtenheft

• Lastenheft: Auftraggeber beschreibt, was er wünscht„Das System soll die Frage aller Fragen suchen“

• Pflichtenheft: Auftragnehmer beschreibt, was er macht„Das System muss (oder wird ) die Frage aller Fragen suchen“

• Frage: wer entwickelt Hefte• Wenn Auftraggeber und Auftragnehmer feststehen,

kann Pflichtenheft inkrementell entwickelt werden• Pflichtenheft teilweise mit UML füllbar• Schwierig: Beim Auftraggeber keine Informatiker


Lastenheft / Pflichtenheft

Struktur [nur ein Vorschlag]0. Administrative Daten: von wem, wann genehmigt, . ..1. Zielbestimmung und Zielgruppen

In welcher Umgebung soll das System eingesetzt werd en?Was soll das System lösen, welche Stakeholder betroff en?

2. Funktionale AnforderungenProduktfunktionen (Anforderungen)Produktschnittstellen

3. Nichtfunktionale AnforderungenQualitätsanforderungenweitere technische Anforderungen

4. Lieferumfang5. Abnahmekriterien6. Anhänge (insbesondere Glossar)


Beispielinhalte Pflichtenheft (0/5)

Versionshistorie: • Dokumenten-ID + Bezeichnung• Versionsnummer • Grund der neuen Version• Ersteller• Zustand (z. B. in Bearbeitung, eingefroren zur

Prüfung, freigegeben, veraltet)• Bei Freigaben: von wem, evtl. mit rechtverbindliche r

Unterschrift

• Versionsmanagement: technisch + Aktenschrank

0. Administrative Daten



• Zentrale Aussage: In welcher Situation soll das neu e System mit welchen Zielen entwickelt werden

• Nennung der StakeholderDefinition: Jemand der Einfluss auf die Anforderungen hat, da er vom System betroffen ist (Systembetroffener)

• Nennung der Ziele des Systems: Was soll für welche Stakeholder erreicht werden

• Beschreibung der funktionalen Ziele durch Use Cases (Diagramm + Dokumentation)

1. Zielbestimmung und Zielgruppen


Beispiel: Use Case-Diagramm


Beispielbeschreibung (1/2)

Handbuch zur Führung von Projekten des KundenReferenzen

Lisa Leitung (zentrale Ansprechpartnerin des Kunden )Fachverant-wortlicher

Projektbüro (startet Use Case durch Auswahl der Funktionalität im zu erstellenden System)

beteiligte Aktoren(Stakeholder)

Mitarbeiter des Projektbüros haben die Möglichkeit, Projekte mit Teilprojekten anzulegen und zu bearbeiten.

Kurzbeschrei-bung

1.0, 30.01.2008, ErstellungVersion

Ali AnalytikerAutor

-Paket

U1Nummer

Projektstruktur bearbeitenName des Use Case


Beispielbeschreibung (2/2)

sehr hoch, System macht ohne Funktionalität keinen Sinn

Kritikalität

Nutzer kann existierendes Projekt auswählen,Nutzer kann Daten eines Teilprojekts ändern

alternative Abläufe

1. Nutzer wählt Funktionalität zur Bearbeitung von Projektstrukturen2. Nutzer legt Projekt mit Projektstandarddaten an3. Nutzer ergänzt neue Teilprojekte4. Nutzer verlässt Funktionalität

typischer Ablauf

Neue Projekte und Teilprojekte sowie Änderungen von Projekten und Teilprojekten wurden vom System übernommen.

Nachbedingun-gen

Die Software ist vollständig installiert und wurde gestartet.

Vorbedingun-gen



• Systematische Aufzählung einzeln nachprüfbarer Funkti onen (jede Anforderung hat eigene ID, ist getrennt lesbar, überprüfbar)

• Ansatz: Verfeinerung der Use Cases durch Aktivitätsdiagramme; Präzisierung der Aktivitätsdiagram me durch Text

• Aktivitätsdiagramme werden inkrementell entwickelt; e rst typischer Ablauf, dann Alternativen ergänzen

• In der Dokumentation steht nur Ergebnis• Literatur: C. Rupp, SOPHIST GROUP, Requirements-

Engineering und – Management, Hanser Fachbuchverlag, 20 04

2. Funktionale Anforderungen


Beispiel: Aktivitätsdiagramm mit typischen Ablauf

Anmerkung: typischer Ablauf ist immer einfache Sequenz von Aktionen, Ausnahme wie hier: einfache Schleifen

Use Case: Projektstruktur bearbeiten


Beispiel:Aktivitätsdiagramm um Alternativen ergänzt


Rupp: Anforderungsformulierung

<Wann?><Randbe-dingung>

muss

soll

wird

das System

-

<wem?> dieMöglichkeitbieten

fähig sein

<Objekt mitRandbedin-gung>

<Prozess-wort>

Typ 1

Typ 3

Typ 2

Typ 1: Selbständige Systemaktivität, System führt Pro zess selbständig durch, z. B. Berechnung des bisherigen Auf wandes eines Projekts durch Abfrage aller Teilprojekte und Erge bnisanzeigeTyp 2: Benutzerinteraktion, System stellt Nutzer die Prozessfunktionalität zur Verfügung, z: B. Verfügbarke it eines Eingabefeldes, um den Projektdaten einzugebenTyp 3: Schnittstellenanforderung, d. h. das System fü hrt einen Prozess in Abhängigkeit von einem Dritten (zum Beispi el einem Fremdsystem) aus, ist an sich passiv und wartet auf ein externesEreignis, z. B. Anfrage einer anderen Bürosoftware nach e iner Übersicht über die laufenden Projekte annehmen


Beispielübersetzung



• Vom System geforderte Eigenschaften, die für Erfolg erfüllt sein müssen

• Achtung! Hier kann jede Anforderung ein KO-Kriterium für das Projekt sein (z. B. Reaktionszeit, Ergonomie)

• Achtung! Hier werden gerne Normen zitiert (z. B. wi e in „Anforderungen an die Dienstqualität 8DIN EN ISO 66272)“ beschrieben); diese Normen sind damit vollständig Vertragsgegenstand

• Bei Erstellung hilft wieder Vorlagennutzung (z. B. aus V-Modell XT)

3. Nichtfunktionale Anforderungen


Definition: Anforderungen an die Dienstqualität

• Mit Anforderungen an die Dienstqualität (quality of service) sind Anforderungen gemeint, die Angaben über das „Wie“ einer anderen, meist funktionalen Anforderung oder des gesamten Systems enthalten. Manchmal werden sie auch Dienstgüte-Anforderungen oder Constraints genannt. Die DIN EN ISO 66272 unterteilt die Dienstgüte in die fünf Merkmale Zuverlässigkeit. Benutzbarkeit, Effizienz, Änderbarkeit und Übertragbarkeit. Sie beschreibt alle möglichen Aspekte der Dienstqualität von Systemen praxistauglich und ordnet sie überschneidungsfrei in einem hierarchischen Schema an.


Beispiele: Anforderungen an die Dienstqualität

• „Das System muss sich im Falle des Auftretens eines Fehlers der Kategorie 1 innerhalb von 20 Stunden wieder auf vollem Leistungsniveau befinden.”

• „Das System muss jede Einzelanfrage an den Bestand der Zentralbibliothek innerhalb von 30 Sekunden ausführen.”

• „Wenn ein Fehler der Kategorie 2 oder 3 auftritt, muss das System den Benutzer auf mögliche Ursachen hinweisen.”

• „Das System muss die Hupe so verwenden, dass diese ihre volle Lautstärke von 112 Dezibel innerha lb von 30 Millisekunden erreicht (Attack-Time).”


Definition: Anforderungen an Benutzungsschnittstelle

• Unter Anforderungen an die Benutzungsschnittstelle ist einerseits zu verstehen, was üblicherweise unte r Mensch-Maschine-Schnittstelle verstanden wird. Also Form und Funktion von Ein- und Ausgabe-Geräten, die dem menschlichen Benutzer die Interaktion mit dem System ermöglichen. Andererseits können auch angrenzende Systeme über eine Benutzungsschnittstelle mit dem zu entwickelnden System verbunden sein, wenn der Zweck diese zu Benutzern macht. Das ist zum Beispiel bei reinen Infrastruktur- oder Middleware-Systemen der Fall, bei denen das System ausschließlich anderen Systemen eine Dienstleitung anbietet.


Beispiele: Anforderungen an Benutzungsschnittstelle

• „Das System muss in der Liste der ausgeliehenen Bücher die Schriftart Helvetica in einer Größe von 11pt verwenden.”

• „Das System muss den „Entleihen“-Button blau darstellen.”

• „Das System muss den angeschlossenen Systemen die Möglichkeit bieten, die gespeicherten Objekte i m Format XY abzurufen.”

• „Das System muss, wenn die Hupe aktiviert wird, diese für fünf Sekunden ertönen lassen.”


Definition: Technische Anforderungen

• Bei dem Typ technische Anforderungen geht es um technische Forderungen, im Gegensatz zu den eher fachlich motivierten funktionalen Anforderungen. Dazu zählen Hardwareanforderungen, Architekturanforderungen, Anforderungen an die Programmiersprachen... Diese Anforderungen werden oft notwendig, weil ein System in ein bestehendes technisches Umfeld eingebettet werden muss oder Verträge die Nutzung einer bestimmten Infrastruktur vorschreiben.


Beispiele: Technische Anforderungen

• „Das System muss mit einer CORBA-Architekturentwickelt werden.”

• „Alle Signalkabel des Systems müssen dem Standard der ETHERNET-Kategorie 5: 10BASE5, 10BASE2 oder 10BASET entsprechen.”

• „Das System muss ausschließlich mit der Programmiersprache Java entwickelt sein.”

• „Das System muss eine Hupe der Firma ,Freighter-Gear', Modell ,Nebelfrei' verwenden.”


Definition: Anforderungen an Entwicklung und Einführung

• Manchmal möchten Stakeholder darauf Einfluss nehmen, in welcher Art und Weise das System entwickelt oder eingeführt werden soll. Zu nennen sind hier unter anderem Anforderungen an die Vorgehensweise (Software-Erstellung, Software-Prüfung), anzuwendende Standards, Hilfsmittel (Tools), die Durchführung von Besprechungen, von Abnahmetests (fachliche Abnahme, betriebliche Abnahme) und die Festlegung von Terminen. Diese Art nennt man An forderungen an die Durchführung der Entwicklung und Einführung.


Beispiele: Anforderungen an Entwicklung und Einführung

• „Der Auftragnehmer muss mit dem Auftraggeber monatliche Reviews der zu erstellenden Dokumente durchführen.”

• „Der Auftragnehmer muss das OOA-Modell mit dem Tool ,quick-OOA‘ entwerfen.”

• „Bei der fachlichen Abnahme des Systems muss der Auftragnehmer darauf achten, dass die Vertreter des Auftraggebers einen Gehörschutz tragen.“


Definition: rechtlich-vertragliche Anforderungen

• Unter rechtlich-vertraglichen Anforderungen sind Angaben zu Zahlungsmeilensteinen, Vertragsstrafen, dem Umgang mit Änderungen der Anforderungen, Eskalationspfade und so weiter zu verstehen.

• Anmerkung: Angaben meist nicht im Pflichtenheft sondern im Projektvertrag


Beispiele: rechtlich-vertragliche Anforderungen

• „Alle Änderungen, die der Auftragnehmer an den Anforderungen vornehmen möchte, müssen vom verantwortlichen Vertreter des Auftraggebers durch Unterschrift genehmigt werden, bevor sie für die Entwicklung relevant werden.”

• „Wird ein Meilenstein vom Auftragnehmer um mehr als zwei Wochen überschritten, ohne ein Ergebnis vorzulegen, oder entspricht mindestens ein Ergebnis zu diesem Zeitpunkt nicht den Anforderungen, so ist der Lenkungskreis einzuberufen.”

• „Der Auftraggeber leistet für jeden Meilenstein, de r abgenommen wurde, ein Drittel der vertraglich vereinbarten Summe für die Entwicklung des Systems.”



• Genaue Festlegung der Produkte (evtl. mit Strukturvorgaben und Umfang)

• Wie wird Software geliefert, wer installiert• Wenn Hardware relevant: wer beschafft was bis

wann• Welche Dokumente sind zu liefern

• Möglich: Schulungen (was, wann, wie lange, wie viele Leute mit welche Ausgangsqualifikation)

4. Lieferumfang



• Klare Klärung, wann Auftraggeber das System als abgenommen bezeichnen muss

• Typisch: es gibt Restpunkte, die aber den Abnahmetermin nicht verschieben

• Wo wird das System von wem abgenommen?• Kunde wird Zeit zur intensiven Prüfung gegeben• Sinnvoll: Orientierung an Use Cases und

Aktivitätsdiagrammen; welche typischen Abläufe werden durchgespielt

• Üblich: Teil- und Zwischenabnahmen (Termine sind zu definieren)

5. Abnahmekriterien


Technische Dokumentation

• „Unten“: Alle Klassen detailliert dokumentiert (Klasse und Methoden), z. B. JavaDoc; es werden zusammenhänge zu anderen Klassen festgehalten

• Zusätzlich: „Big Pictures“ mit Zusammenhängen mehrerer Klassen und Pakete + evtl. Detaildarstellungen, z. B. Zustandsdiagramme

• Kommerzielle Werkzeuge erlauben Dokumentengenerierung aus UML-Werkzeugen


Zentrale technische Dokumente (1/6)

Klassendiagramme



Sequenzdiagramme



Zustandsdiagramme



Paketdiagramme



Komponentendiagramme



Verteilungsdiagramme


Änderungsverfolgung

• Dokumenten müssen änderbar sein, damit sie aktuell bleiben

• Kompromiss zwischen Aktualisierung und Projektfortschritt

• Änderungen verfolgen; Zustand der Dokumente sichtbar machen

• Studentische Projekte: Version 1.0 der Dokumente im Projektverlauf verabschieden; Dokumente zum Projektende aktualisieren

7. Projektdokumentation Dokumentenarten Inhalte von...

Documents

Transcript of 7. Projektdokumentation Dokumentenarten Inhalte von...