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.

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