Softwaredokumentation Wie erstelle ich eine gute Dokumentation? Jena, 05.02.2018
2 Agenda 1. Zu meiner Person 2. Softwaredokumentation 3. Wie erstelle 4. Ich 5. gute 6. Dokumentation? 7. Podiumsdiskussion
3 Zu meiner Person Zu meiner Person
Zu meiner Person Bachelorstudium Angewandte Informatik Masterstudium Technische Redaktion & Multimediale Dokumentation seit 2016 bei dictajet Dienstleister für Technische Dokumentation, Informationsmanagement und Organisationsentwicklung Mess- und Diagnosetechnik für Bahninfrastruktur 4
5 Softwaredokumentation Software- Dokumentation
Softwaredokumentation ProdHaftG: Instruktionsfehler gelten als Fehler, die Haftungsfall begründen Projektdokumentation entsprechend des Entwicklungsprozess (Vorgehensmodell) Wasserfall Spiral Scrum Anwenderhandbuch 6
7 Wie erstelle Wie erstelle
8 Wie erstelle Erstellungsprozess Vorbereitung Recherche Entwurf Review Release Übersetzung
Erstellungsprozess: Vorbereitung Dokumentation in der Projektplanung einplanen Zuständigkeiten Aufgabenpakete Zeitplan Zielgruppenanalyse: Persona-Methode Wer? Macht was? Wie? 9
10 Erstellungsprozess: Vorbereitung Tools MS Word Bildbearbeitungsprogramme Redaktionssystem Wiki-basiertes System Dokumenten-Management-System
Erstellungsprozess: Recherche Normen & Richtlinien vorhandene Informationen Vertriebsunterlagen Prospekte Kundenanforderungen: Sprache, Ausgabeformat, Abbildungskonzept Screenshots Schemata Diagramme 11
12 Erstellungsprozess: Abbildungen 3 2 1
13 Erstellungsprozess: Abbildungen 2 1 3
Erstellungsprozess: Entwurf Ganz einfach: Struktur planen Texte schreiben: Style Guide/Redaktionsleitfaden Bilder erstellen Bilder bearbeiten Stolpersteine: Anpassungen an der Oberfläche neue Features zu straffe Zeitplanung 14
Erstellungsprozess: Review Technische Review Sprachliche Review Grafische Review Festlegungen in der Review festhalten Style Guide/Redaktionsleitfaden 15
Erstellungsprozess: Release Qualitätssicherung interner Prozess zur Veröffentlichung Merkmale einer Dokumentation Vollständigkeit Richtigkeit Pünktlichkeit Einheitlichkeit 16
Erstellung: Übersetzung Terminologie Synonyme Abkürzungen Produktspezifische Ausdrücke Fachjargon (Zielgruppenanalyse) Beispiel: triggern intern vs. extern Übersetzen Austauschformate (Erstellungstool) Translation-Memory-System 17
18 Ich Ich
Ich Ein-Mann-Redaktion Technische Redaktion externe Dienstleister 19
20 gute gute
21 gute Qualitätsmerkmale nach DIN 82079 Verfügbarkeit Zielgruppengerechtigkeit Normengerechtigkeit ISO 26511 26515 Struktur Verständlichkeit Design & Layout
22 Dokumentation? Dokumentation?
Dokumentation? Überbegriff Dokumenttypen, wie Anwenderhandbuch Teil des Produktes muss laut Normen Merkmale erfüllen 23
24 Dokumentation? Grundlagen der Technischen Dokumentation Anleitungen verständlich und normengerecht erstellen, Lars Kothes, 2011 Technische Dokumentation Praktische Anleitungen und Beispiele, Dietrich Juhl, 2005 Texten für die Technik Leitfaden für Praxis und Studium, Andreas Baumert und Annette Verhein-Jarren, 2012 Microsoft Manual of Style Your everyday guide to usage, terminology, and style for professional technical communications, 2012 Software-Dokumentation Praxis Lösungen, Gertrud Grünwied, 2012
25 Vielen Dank!