Vom Startschuss eines oder mehrerer Projekte mit dem Ziel einer Implementierung bis zum GoLive ist es ein langer Weg. Daher ist die begleitende Dokumentation eines solchen Vorhabens eine essentielle Aufgabe, um das zielgerichtete Steuern und die Kontrolle der damit verbunden Aktivitäten im Projektteam zu garantieren.
Die Dokumentation bezieht sich auf verschiedene Ebenen eines Implementierungsprojektes und muss daher die verschiedenste Formate von Text über Bilder und Code integrieren können. Die Anforderungen an die Dokumentationssysteme sind ebenso vielseitig.
PLM Open Hours - Dokumentation von Projekten mit Implementierungsanteil
1. Intelliact AG
Siewerdtstrasse 8
CH-8050 Zürich
Tel. +41 (44) 315 67 40
Mail mail@intelliact.ch
Web http://www.intelliact.ch
Dokumentation von Projekten mit Implementierungsanteil
Marco Egli und Kai Uffman, 7. Oktober 2013
INTELLIACT
PLM OPEN HOURS
2. Inhalt
Für was braucht es eine Dokumentation?
(Ausgangslage)
Verschiedene Rollen haben verschiedene Bedürfnisse
(Herausforderung und Anforderungen)
UML löst alle Probleme?!
(Dokumentationsvarianten und Bewertung in Szenarien)
Zusammenfassung
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 3
3. Für was braucht es eine Dokumentation?
Vom Startschuss eines oder mehrerer Projekte mit dem
Ziel einer Implementierung bis zum GoLive ist es ein langer
Weg. Daher ist die begleitende Dokumentation eines
solchen Vorhabens eine essentielle Aufgabe, um das
zielgerichtete Steuern und die Kontrolle der damit
verbunden Aktivitäten im Projektteam zu garantieren.
Die Dokumentation bezieht sich auf verschiedene Ebenen
eines Implementierungsprojektes und muss daher die
verschiedenste Formate von Text über Bilder und Code
integrieren können. Die Anforderungen an die
Dokumentationssysteme sind ebenso vielseitig.
Diese Anforderungen und Arbeitsweisen mit
verschiedenen Tools werden in diesen Open Hours
vorgestellt und diskutiert.
PLM Open Hours - Dokumentation von PLM-Projekten mit Implementierungsanteil 4
ABSTRACT
4. Verschiedene Ebenen
Qualität
Prozessdokumentation
Anwenderdokumentation
Applikationsdokumentation
Codedokumentation
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 9
AUSGANGSLAGE
Manager
User
Entwickler
Projektteam
Fokus in dieser Präsentation
Anforderung
Umsetzung
5. Für was braucht es eine Entwicklungsdokumentation?
Vorgaben in Form von Lasten- und Pflichtenheften
Beschreibung der Ziele und Anforderungen
Nachweis der einzelnen Versionen auf Grund von Veränderungen
Erfolgreiche und erfolglose Entwicklungsrichtungen
http://de.wikipedia.org/wiki/Softwaredokumentation
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 10
AUSGANGSLAGE
6. ZIEL: EINE ZENTRALE, LEBENDIGE
GESAMTDOKUMENTATION
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 11
7. Was muss eine Dokumentation leisten ?
Lifecycle
Versionsmanagement
Vergleich von Entwicklungsständen
Tracebility
Durchgängigkeit und Zusammenhänge
Gesamtdokumentation auf Basis einer modularen Dokumentation
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 12
HERAUSFORDERUNGEN
8. Was muss eine Dokumentation leisten ?
Bearbeiten
Usability
Kombination von Fliesstext, Bildern, Tabellen, Diragrammen
Vorlagen
Zusammenarbeit
Paralleles Editieren, auch mit Externen
Review- und Kommentar-möglichkeiten
Volltextsuche
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 13
HERAUSFORDERUNGEN
9. Übersicht
Office Dokumente in einem DMS
z.B. Word und Excel in Box
Dokumentation in einem Wiki
z.B. in einem Mediawiki-Intranet
Textdateien (mit Markup) unter Versionskontrolle (Sourcecode-
Management)
z.B. Markdown unter Subversion-Verwaltung
Softwaredokumentationstool
z.B. Enterprise Architect
Redaktionssystem
z.B. SCHEMA ST4
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 19
DOKUMENTATIONSVARIANTEN
10. Mögliche Arbeitsweise
Bearbeitung der Dokumentation
mit Office-Applikationen
Verwaltung der Dokumente in
einem DMS für erweiterten
Funktionen
Versionierung
Volltextsuche
Zusammenarbeit und
Berechtigungskonzept
Publikation
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 20
OFFICE DOKUMENTE IN EINEM DMS
DMS (Box, Sharepoint, Alfresco, etc.)
Office Applikationen
DMS
Client
Anwendungsfall 1
Architekturskizze
Sequenzdiagramm
Anforderungen
Anwendungsfall 2
Datenmodell
Spezifikation
Produktiv
Projekt
Anwendungsfall 2
Spezifikation
kopieren / zusammenfügen
11. Stärken
Sehr niedrige Einstiegshürden.
Umgang mit Office ist allen
bekannt
Echtes WYSIWYG und
umfangreiche Möglichkeiten zur
Formatierung
Schwächen
Traceability nur über
Konventionen und manuelle
Nummerierung
Abgrenzung von Entwicklungs-
und Produktionsstand schwierig
und umständlich
Paralleles Bearbeiten wird
ungenügend unterstützt
Einbetten von Skizzen und
Diagrammen in Textdokumente
ist umständlich
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 21
Bewertung
OFFICE DOKUMENTE IN EINEM DMS
12. Mögliche Arbeitsweise
Erstellung von Wiki-Seiten
anstelle von Dokumenten
Erweiterte Funktionen abhängig
von der verwendeten Lösung
Volltextsuche
Parallele Bearbeitung
Berechtigungskonzept
Vereinfachte Traceability über
die Verlinkung von Seiten
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 22
DOKUMENTATION IN EINEM WIKI
Wiki (Confluence, Editme, Mindtouch etc.)
Wiki-Client (Browser)
page
page
Links
page
page
Backlinks
Hyperlinks
13. Stärken
Formatierung über WYSIWYG
Gemeinsame Bearbeitung und
Versionierung gehört zu den
Kernfunktionalitäten
Traceability über Links
Schwächen
Abgrenzung von Entwicklungs-
und Produktionsstand nicht
möglich
Einbettung von Bildern oder
UML-Diagrammen ist
umständlich
Berechtigungsabgrenzung über
mehrere Projekte
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 23
Bewertung
DOKUMENTATION IN EINEM WIKI
14. Mögliche Arbeitsweise
Als Editor genügt ein Texteditor
bzw. die Entwicklungsumgebung
Formatierung mit einfacher
Auszeichnungssprache (z.B.
Markdown)
Strukturierung, Versionierung und
Zusammenarbeit funktionieren
analog der Softwareentwicklung
Verwaltung mehrere Zweige
(Produktion, Entwicklung)
Versionierung über alle Änderungen
Unterstützung beim
Zusammenführen
Umfangreiche
Vergleichsmöglichkeiten
Mitarbeit ohne intalliertem Client mit
Web-Client auf den Repo-Server
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 24
TEXTDATEIEN UNTER VERSIONSKONTROLLE
Repository Server (Github, Beanstalk, Google
Code, etc.)
Texteditor
IDE
Repo-
Client
Report
PDF, HTML
edit
diff
history
preview
15. Stärken
Niedrige Einstiegshürden. Keine
Zusatzinstallation notwendig
Zusammenarbeit im Team wird
gut unterstützt. Auch über die
Firmengrenzen hinweg.
Hervorragende Unterstützung
für die Versionierung und die
Abgrenzung von Entwicklungs-
und Produktionstand
Sourcecode-Dokumentation
Schwächen
Traceability nur über
Konventionen und manuelle
Nummerierung
Einbettung von Bildern oder
UML-Diagrammen ist
umständlich
Formatiertes Dokument nur
über einen (Web-)Client oder ein
Rendering nach PDF oder HTML
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 25
Bewertung
TEXTDATEIEN UNTER VERSIONSKONTROLLE
16. Mögliche Arbeitsweise
Grafische Darstellung von
Zusammenhängen wie
Rollen
Anwendungsfällen
Prozessen (Sequenzdiagramm)
Automatische Ableitung von
Testfällen als RTF, PDF, HTML
Traceability als Projekt in
Dokumentationstool
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 26
SOFTWAREDOKUMENTATIONSTOOL
SW-Dokumentationstool (Enterprise
Architect, …)
Tool-Frontend
Anwendungsfall 1
Anforderungen
Anwendungsfall 2
Office
Applikationen
17. Stärken
Traceability automatisch
gepflegt
Änderungen wirken sich
vollständig aus
Schwächen
Komplexer Aufbau, daher
schwierig anzuwenden
Schwer mit anderer
Dokumentation zu integrieren
Extra Lizenzkosten für das
Dokumentationstool
Formatiertes Gesamtdokument
nur über Prozess erreichbar
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 27
Bewertung
SOFTWAREDOKUMENTATIONSTOOL
18. Mögliche Arbeitsweise
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 28
REDAKTIONSSYSTEM
Dokumentations-
struktur
010
101
010
101
Arbeitsdokumente
Editierbar
Projektdokumente
Textbaustein Neutralformate
Dokumentations-
resultate
Dokumentations-
elemente
Metadaten zur
Klassifzierung und
Autorisierung
Klasse
Verantwortlicher
Merkmale
Textbaustein
Diagramm
010
101 Sourcecode
…
Inhalt / Templates Struktur / Prozesse Review / Control /
Austausch mit Extern
Publikation
Definieren Editieren Freigabe
19. Stärken
Starke und vielfältige
Funktionalität
Beherrschung von Komplexen
Zusammenhängen
Zentrale Pflege der
Dokumentationsstruktur /-
prozesse
Schwächen
Hoher Aufwand für
Dokumentationsplanung/
-vorbereitung
Administration
Hohe Kosten für
Anschaffung,
Bereitstellungen
Lizenzen
ggf. Schnittstellen
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 29
Bewertung
REDAKTIONSSYSTEM
20. Lösungen im Vergleich
Anforderung Dokumente
& DMS
Wiki Versionierte
Textdateien
Dokutool Redaktions-
system
Lifecycle Versionsmanagement ++ + ++ ++ ++
Vergleich von
Entwicklungsständen
- + ++ - +
Traceability Durchgängigkeit und
Zusammenhänge
- - - ++ ++
Gesamtdokumentation auf Basis
einer modularen Dokumentation
- + + - ++
Bearbeitung Usability ++ + + -- -
Kombination von Fliesstext,
Bildern, Tabellen, Diragrammen
++ + - -- ++
Vorlagen + + + + +
Zusammenarbeit Paralleles
Editieren, auch mit Externen
+ - ++ -- +
Review- und Kommentar-
möglichkeiten
+ + + - +
Volltextsuche + + + - +
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 32
ZUSAMMENFASSUNG
21. Best Practice
Definition im Projekt
Was wird in welcher Form dokumentiert
Wer ist für welche Dokumentationsanteile verantwortlich
Zentrale Dokumente
Regelung der Langzeitverfügbarkeit
Gesamtdokumentation nicht im Projektkontext
Methodik für die Projektabgrenzung
Systemspezifische Templates
PLM Open Hours _ Dokumentation von Projekten mit Implementierungsanteil _ 07.10.2013 34
ZUSAMMENFASSUNG