Dokumentation Wie aus Hass Liebe wird. Carola Köhntopp

Transkript

1 Dokumentation Wie aus Hass Liebe wird

2 Moin! PHP-Dokumentationsteam 2

3 Und das Auditorium? Eigene Position? Teamleader? Sysadmin? Programmierer? Grafiker? Support? Design von Userinterfaces? Öffentlichkeitsarbeit/Teambuilding? Consultant/Trainer? Dokumentation? 3

4 Und das Auditorium? Wann erwarten Sie Dokumentation? Wie soll diese Dokumentation gestaltet sein? Wo möchten Sie die Dokumentation finden? Was soll dokumentiert sein? 4

5 Übersicht Dokumentation Wann? Wozu? Wer? Wo? Wie? Dokumentationsfelder Sourcecode Developer Administratoren User Dokumentationstypen Externe Produktdoku Interne Produktdoku Prozessdoku 5

6 Dokumentation Einmal mit Profis arbeiten! Wie sieht ein Profiprojekt aus? Strukturierter Code Klare API Nachvollziehbare Programmiermodelle Geplante Infrastruktur Logische, gleichartige Modelle für das Netzwerk Keine unnötigen Abhängigkeiten Zielführende Roadmap Und: Dokumentation. Viel Dokumentation. 6

7 Dokumentation Profis sind auch nur Leute wie du und ich Unterschiede? Erst denken, dann handeln Eine saubere Konzeption spart Arbeit bei der Ausführung Die richtigen Leute für die richtigen Aufgaben schafft Erfolgserlebnisse und Motivation 7

8 Dokumentation Use the source, Luke! Exaktestmögliche Darstellung des Programms/eines Netzwerks Nicht navigierbar Keine Beschreibung des erwarteten Verhaltens Besser bei deskriptiven Sprachen (SQL, puppet), aber auch dort ist Kontext notwendig Keine Information über das zugrundeliegende Design Keine Abschätzung über leistungskritische Stellen und deren Auswirkungen Keine explizite Darstellungen der Systemanforderungen 8

9 Dokumentation - Wann? Immer! Beim Schreiben von Code Beim Ändern von Code Beim Erstellen eines Netzplans Beim Ändern einer API Beim Ändern von Requirements Beim Ändern von Workflows Beim Ändern des Userinterface Beim Auswerten von Supportanfragen Beim Erstellen von Pflichten-/Lastenheften... 9

10 Dokumentation - Wozu? Nachvollziehbarkeit Code Funktionalität Struktur (Applikations-) Verhalten Environment/Requirements Wartbarkeit Erleichterte Fehlersuche Verbesserte Bugreports Vermindern von Einarbeitungszeiten Supportaufwand 10

11 Dokumentation - Wozu? Verbessern der Kommunikation Sysadmin vs. Entwickler Entwickler vs. Entwickler User vs. Support Support vs. Entwickler/Sysadmin Sales vs. Development Customer vs. Development 11

12 Dokumentation - Wer? Der Sysadmin Der Datenbankadmin Der Programmierer Das Quality-Management Die Betatester Die Supportler Die Trainer Die Projektleitung Das Dokumentationsteam 12

13 Dokumentation - Wo? Im Sourcecode In Config-Files Im Dokumentations-/Redaktionssystem Im Pflichten-/Lastenheft 13

14 Dokumentation Wie? Zielgruppenspezifisch Einfache, klare Sprache Möglichst präzise Beschreibungen So zielführend und kompakt als möglich Unter Berücksichtigung verschiedener Lerntypen Viele Wege führen nach Rom! 14

15 Dokumentation Anforderungen versioniert aktuell vollständig 15

16 Dokumentation WWW? 16

17 Dokumentation Sourcecode 17

18 Dokumentation Developer 18

19 Dokumentation Administrator 19

20 Dokumentation Enduser 20

21 Dokumentation Externe Produktdoku Anleitung für Benutzer Administratoren Arbeitsgrundlage für Trainer Entscheider Evtl. Vertragsgegenstand Leistungsbeschreibung Gewährleistung 21

22 Dokumentation Interne Produktdoku Bisherige und künftige Prozessbeteiligte (Was kommt eigentlich auf mich zu?) Kommunikation (Mit wem muss ich sprechen?) Koordination (Mit wem muss ich zusammenarbeiten?) Wissensspeicher (Wo finde ich Information über...?) 22

23 Dokumentation - Prozessdokumentation Beschreibung des Entwicklungsablaufs Koordination Prozessverbesserung Rechtliche Absicherung Vereinfachte Weiterentwicklung 23

24 Dokumentationspraxis Bevor Sie Ihr neu erworbenes Programm in Betrieb nehmen, lesen Sie bitte zuerst die Bedienungsanleitung (mich) vollständig durch. Haben Sie Geduld. Sie haben Aussicht, bald in den Genuss des Programm-Nutzens zu kommen. Denken Sie immer mit, lernen Sie dauernd um. Versetzen Sie sich in meine Lage. Verstehen Sie mich recht, dann können Sie auch mit mir umgehen. Erfolg hat auf die Dauer nur der Tüchtige. 24

25 Dokumentationspraxis Geben Sie sich Mühe und lassen Sie nicht nach in Ihrer fortgesetzten Anstrengung. Information findet, wer Information sucht. Quälen Sie sich ruhig mal durch mein Inhalts- und Stichwortverzeichnis. Ihre Ungeduld in Ehren, aber ohne Fleiß kein Preis. Zuerst müssen Sie mal verstehen, wie das Programm funktioniert. Na hören Sie, das kann doch nicht so kompliziert sein! Unterstehen Sie sich, mich links liegen zu lassen und am Programm unangeleitet herumzuspielen. Wenn Sie das Programm beschädigen, dann auf Ihre eigene Verantwortung... 25

26 Dokumentationspraxis Planen Alle Aktivitäten auflisten, die zur Erstellung der Anleitung notwendig sind. Alle Personen auflisten, die über Informationen verfügen Für die einzelnen Bearbeitungsphasen Zeitablaufplan erstellen Ständig korrigieren, wenn es Abweichungen gibt Bessere Zeitbedarfsschätzungen für zukünftige Dokuprojekte Stichwort: Agile Entwicklung 26

27 Dokumentationspraxis Programm-/Netzwerkanalyse Alle verfügbaren Informationen zusammentragen. Lastenheft, Angebotstexte, Screenshots, UML-Diagramme, Netzwerkpläne, Entwicklungs- und Projektunterlagen,... Alle Fachleute, die mit dem Produkt zu tun haben, befragen Development, Support, Sales, Projektleitung Folgende Punkte müssen genau definiert sein: Was kann das Programm/die Architektur Welche Idee/welches Konzept liegt zugrunde Wofür wird es eingesetzt Wo liegen die Vorteile gegenüber möglichen Alternativen Welchen Nebennutzen wird generiert Welche Systemanforderungen sind notwendig 27

28 Dokumentationspraxis Zielgruppenanalyse Am Bedarf der Zielgruppe orientieren (nicht beschreiben, was für ein tolles Programm der Leser erworben hat, wenn er nur wissen will, wie man fett schreibt). Bei der Zielgruppe folgende Punkte beachten: Informationsbedarf Vorkenntnisse/Qualifikation Zumutbares Fachvokabular Lernverhalten Welche Information erwartet der Leser an welcher Stelle? 28

29 Dokumentationspraxis Strukturieren Alle Unterlagen in sachlogischer Folge ordnen Nacheinander alle Informationen in Stichwörtern auf einzelne Seiten übertragen Informationen sinnvoll aufteilen, z.b. Layer2-Links samt Spanningtree Layer3-Verbindungen samt Routing... Ergänzen, wo noch Informationen fehlen Alles durchnumerieren -> Checkliste und grobes Inhaltsverzeichnis 29

30 Dokumentationspraxis Text und Bild Welche Aussagen lassen sich leichter mit einem Bild darstellen? Text und Bild sollen sich gegenseitig ergänzen Eindeutige Zuordnung von Bild und Text 30

31 Dokumentationspraxis Formulieren Texte kurz, prägnant und treffend formulieren Weitschweifige Texte vermeiden Nicht versuchen, den Leser autoritär zu gängeln Gestalten Die Anleitungen möglichst interessant gestalten Zum Durchlesen verleiten! 31

32 Dokumentationspraxis Qualitätssicherung Begutachten der Dokumentation unter verschiedenen Gesichtspunkten Sinn Aufbau Verständlichkeit Vollständigkeit Sicherheitshinweise,... Tippfehler sind heimtückisch! Texte gegenlesen lassen Besonderes Augenmerk auf Verweise, Indexe etc. legen. 32

33 Dokumentationspraxis Tauglichkeits-Test Ein sehr heikles Thema! Zeit Ressourcen Nichterkennen der Notwendigkeit Dokumentation von zielgruppenähnlichen Testpersonen vor Ort am lebenden Objekt testen lassen Neulinge haben meist mit Schwierigkeiten zu kämpfen, auf die man selbst nie gekommen wäre! 33

34 Dokumentationspraxis Regelmäßige Prüfung und Aktualisierung Nach jeder Änderung aktualisieren Neue Informationen direkt einpflegen Routinemäßige Tests durchführen (z.b. wöchentlich für einen bestimmten, wechselnden Bereich eine Notfallübung durchführen) 34

35 Die Königsklasse Mehrsprachig Basissprache festlegen Hauptdokumentation schreiben Übersetzer finden Übersetzungen anfertigen Übersetzungen synchron zur Basis halten 35

36 Fazit Doku entsteht nicht von allein Hoher Kommunikationsaufwand mit der Zielgruppe Sprache der Zielgruppe Denk- und Lernweise der Zielgruppe Gute Dokumentation Braucht eine Konzeption und eine permanente Betreuung Akzeptanzfördernd Imagefördernd Entwicklungsfördernd Kommunikationsfördernd Aufwandssenkend 36

37 Fazit Nicht der Entwickler/Sysadmin schreibt die vollständige Dokumentation! Dokuteam Evtl. Translationteam Dokumentation entsteht aus und unter aktiver Mitwirkung der Zielgruppe Developer Administratoren Anwender Leute, die sich um die Dokumentation eines Projekts kümmern, sind ebenso wichtig wie die Programmierer 37

38 Tools Code Doxygen,... Netzwerk Visio Metasploit Intermapper,... Festhalten der Information in Wiki/Redaktionssystem der Wahl Storageformat docbook 38

39 Interaktiv! Fragen fragen. Jetzt! Fragen fragen. Später. Per . 39

40 Vielen Dank für die Aufmerksamkeit! 40