Modul Software Komponenten20 – SWK Dokumentation

Martin Jud

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 2

Inhalt

1. Übersicht & Repetition Doku allgemein

2. Systemspezifikation aus Sicht SWK

1. Übersicht Doku & Repetition

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 4

Nutzen der Dokumentation

Viele Dokumente wie z.B. Software-architektur sind bereits (Zwischen-) Produkte des Entwicklungsprozesses.

Dokumentationsarbeit hilft beim Problemverständnis (z.B. Kunden-anforderungen, Softwareanforderungen) und bei der Konsensbildung (z.B. Architekturmodelle, Projektpläne).

Dokumentation leistet einen Beitrag zur Wissenssicherung (80% der Softwareentwicklung ist Pflege bestehender Systeme).

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 5

Dokumentation: Was? – Für wen?

Projektplanung

Konfig.-Management

Qualitätssicherung

Verifikation & Validierung

Entwurf

Code

Test

Anforderungen

Installation

Betrieb

Prozess

Produkt

Entwickler-innen

Kunden

Was

wir

d do

kum

entie

rt ?

Für w

en w

ird

doku

men

tiert

?

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 6

Dokumentation nach IEEE

SPMPsoftware project management planProjektplanung

SCMPsoftware configuration management planKonfig.-Management

STDsoftware test documentationTest

Source CodeCode

User’s manualBetrieb

SQAPsoftware quality assurance planQualitätssicherung

SVVPsoftware validation & verification planVerifikation & Validierung

SRSsoftware requirements specificationsAnforderungen

Customer-orientedDeveloper-oriented

SDDsoftware design documentEntwurf Architecture

Detailed design

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 7

Agile Dokumentation?

Agile Manifesto:“working software over comprehensive documentation” *)– Wie schafft man die Gratwanderung zwischen dem Zuviel

und dem Zuwenig an Dokumentation? – Wie erreicht man die Balance zwischen Aufwand und Nutzen?– Welche Dokumentation ist nützlich?

Agile Dokumentation– legt aus dem Projektkontext heraus bewusst fest,

was dokumentiert werden soll,– ist inhaltlich aktuell und korrekt,

gleichzeitig aber kompakt und gut strukturiert,– ist nicht lästige Pflicht, sondern effektiver Beitrag

zur Unterstützung der anderen Projektaufgaben.

*) “That is, while there is value in the items on the right, we value the items on the left more”

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 8

HTAgil Dokumente

Dokumentation Kundenanforderungen• Kundenanforderungs-Dokument

Dokumentation Systemspezifikation• Systemspezifikations-Dokument

Software Dokumente • Code und innere Dokumentation (z.B. Javadoc) / Kommentare • Software Test Dokument• Bedienungsanleitung

Unterstützende Dokumente• Projekt Management Plan

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 9

HTAgil Dokument: Kundenanforderung

1. Zielbestimmung

2. Produkteinsatz

3. Produktübersicht

4. Produktfunktionen

5. Produktdaten

6. Qualitätsanforderungen Leistungsanforderungen

7. Ergänzungen

Warum soll das Produkt entwickelt werden?

Von wem wird das Produkt ver-wendet? Wozu wird das Produkt verwendet? (UseCase Übersicht)

Abgrenzung und Umgebung: Schnitt-stellen zu Nutzern und Drittsystemen

Arbeitsabläufe – Akteure –Funktionalität – UseCases . . .

Wichtige Daten und Mengengerüste

Zuverlässigkeit, Portierbarkeit, . . . Verarbeitungszeit, Kommunikation, . . .

Je nach Projekt / Produkt

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 10

HTAgil Dokument: Systemspezifikation

1. Systemübersicht

2. Architektur-Modelle

3. Spezifikation externe Schnittstellen

4. Softwareanforderungen

5. Environment-Anforderungen

Systemidee im Hinblick auf einen Lösungsansatz

Struktur von Code & Daten, der Anwendung und deren Verteilung

Schnittstellen zu Drittsystemen, aber auch zu Subsystemen

Verfeinerung und Konkretisierungder Kundenanforderungen mit Bezug zur Umsetzung in der Architektur (vgl. SW 9 Was vs. Wie)

Hardware, Betriebssystem, VM

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 11

Umgang mit Änderungen

Beim iterativ-inkrementellen Vorgehen haben verschiedene Releases unter-schiedliche Spezifikationen und Architekturen, die möglicherweise unterein-ander nicht konsistent sind.

Konsistente Versionen in entsprechenden Unterkapiteln oderkonsistente Version der Systemspezifikation pro Release ablegenSYS.SPEZIFIKATION MasterMind1. Systemübersicht2. Architektur-Modell2.1 Architektur Stand Release #12.2 Architektur Stand Release #2 3. Spec. externe Schnittstellen4. SW-Anforderungen4.1 SW-Anf. Stand Release #14.2 SW-Anf. Stand Release #2 5. Environment Anforderungen

SYS.SPEZIFIKATION MasterMind Release #11. Systemübersicht2. Architektur-Modell3. Spec. ext. Schnittst.4. SW-Anforderungen5. Environment Anf.

SYS.SPEZIFIKATION MasterMind Release #21. Systemübersicht2. Architektur-Modell3. Spec. ext. Schnittst.4. SW-Anforderungen5. Environment Anf.

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 12

HTAgil Projektmanagement Plan

1. Einleitung

2. Projektorganisation

3. Projektführung

4. Technischer Prozess

5. Projektunterstützung

6. Anhänge

Projektübersicht / Referenzen / Begriffe & Abkürzungen

Rollen & Zuständigkeiten, organisatorische Schnittstellen

Rahmenplan (Meilensteine) / Risikomanagement / Arbeitspläne pro Iteration / Projektkontrolle

Methoden & Werkzeuge / Infrastruktur

Konfigurations-Management, Dokumentationsplanung, Review-planung, Qualitätssicherung (QS), . . .

Je nach Projekt / Produkt

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 13

Versionskontrolle

Dokumente entstehen und verändern sich im Laufe jedes Entwicklungs-prozesses, nicht nur bei iterativ-inkrementellem Vorgehen.

Es ist daher wichtig, den Stand eines Dokumentes zu kennen.

Vielfach ist es eine Prozessvorgabe, dass die Produktentstehung aus den Dokumenten nachvollziehbar sein muss.

Dokumente müssen einer Versionsverwaltung unterworfen werden.

2. Systemspezifikationaus Sicht SWK

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 15

At the root of all the problems we have with software

lies the failure of software developers

to document design decisions

in a way that allows those decisions

to be reviewed,

to guide the implementors,

to guide the testers and

to guide those who will maintain it in the future.

David L. Parnas, Disciplined Quality Software Construction, USI 2008

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 16

Kundenanforderungen vs. SW-Spezifikation II

Spezifikation„SW-

Anforderung“

Organisation nach

Subsystemen

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 17

Systemspezifikation – Vorgehen

Anforderungen verfeinern, spezifizieren

Architekturübersicht erstellen, Realisierbarkeit prüfen

Datenmodell erstellen, GUI-Skizzen ....

Anforderungen an die Umgebung (Environment) festhalten

Die Verfeinerung der Anforderungen und der Architektur erfolgt „Hand in Hand“

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 18

Vorgehen beim Architekturentwurf

1. Aufgabe analysieren

• Anforderungen verstehen

• Vorhandene bzw. beschaffbare Technologien und Mittel analysieren

3. Lösungskonzept prüfen

• Anforderungen erfüllt?

• Softwaretechnisch gut?

• Wirtschaftlich?

2. Architektur modellieren• Grundlegende

Systemarchitektur festlegen (Architekturmuster)

• Festlegung des Architekturstils• Modularisieren• Nebenläufige Prozesse

gliedern• Wiederverwendungs- und

Beschaffungsentscheide treffen• Ressourcen zuordnen• Aspektbezogene Teilkonzepte

für Querschnittsaufgaben erstellen

• Lösungskonzept erstellen

Aus der Vorlesung Software-Engineering von Martin Glinz, Uni Zürich

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 19

HTAgil Systemspezifikation

1. Systemübersicht/Kontext

2. Modelle2.1 Analyse-Modell 2.2 Architektur-Modell - Conceptual View (Logical View, Kontext-Sicht) -Structure View (Module View, Implementation View, Bausteinsicht) -Execution View (Component&Connector View, Process View, Laufzeitsicht) - Allocation View (Deployment View, Verteilungssicht) 2.3 Daten-Modell

3. Spezifikation externe Schnittstellen

4. Softwareanforderungen - Unterschiedliche Ordnungsprinzipien -Funktionale und nicht-funktionale Anforderungen

5. Environment-Anforderungen (HW, BS, VM)

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 20

HTAgil Systemspezifikation (1)

1. Systemübersicht/KontextZeichne ein Kontext-Diagramm, das alle Nutzer/innen (Rollen) und Drittsysteme, mit denen das zu entwickelnde System kommuniziert, enthält, und zeige die entsprechenden Datenflüsse auf.

Unterhalt

Kunde

Bank-Zentrale

Bankomat

gewünschte Funktion,

Karte, Pin, Konto, Betrag

Abbuchen, KontostandAnfrage

Kontoinfo, Quittierung

Geld

Geld, Quittung

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 21

HTAgil Systemspezifikation (2)

2. Modelle

2.1 Analyse-Modell

2.2 Architektur-Modell

- Conceptual View

- Execution View

- Allocation View

2.3 Daten-Modell

Zu Kapitel 2.1: Bei Bedarf ein OOA-Modell zur Analyse der Anforderungen erstellen

Zu Kapitel 2.2:- Conceptual View(Logical View, Kontext-Sicht)

- Structure View(Module View, ImplementationView, Bausteinsicht)

- Execution View(Component&Connector View,Process View, Laufzeitsicht)

- Allocation View(Deployment View, Verteilung)

Zu Kapitel 2.3: Bei Bedarf ein konzeptionelles ER-Diagramm erstellen (ableiten aus OOA-Modell)

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 22

Conceptual View (1)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 23

Conceptual View (2)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 24

Structure View (1)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 25

Structure View (2)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 26

Allocation View (1)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 27

Allocation View (2)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 28

Allocation View (3)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 29

HTAgil Systemspezifikation (3)

3. Spezifikation Schnittstellen

Describe the methods of interaction and the rules governing those interactions.

– The methods of interaction include the mechanisms for invoking or interrupting the entity, for communicating through parameters, common data areas or messages, and for direct access to internaldata.

– The rules governing the interaction include the communications protocol, data format, acceptable values, and the meaning of each value.

Provide a description of the input ranges, the meaning of inputs and outputs, the type and format of each input or output, and output error codes.

For User Interfaces include inputs, screen formats, and a complete description of the interactive language.

Angepasster Auszug aus IEEE Std 1016-1998 SOFTWARE DESIGN DESCRIPTIONS Copyright © 1998 IEEE

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 30

Schnittstellen (1)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 31

Schnittstellen (2)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 32

Schnittstellen (3)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 33

Schnittstellen (4)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06

© HSLU T&A, 30.11.2008 Modul SWK - 20-Doku - Martin Jud 34

Schnittstellen (5)Auszug aus der SDD der DA "Service-Manager" A.Aeschbach, D.Jossen 24.Nov.06