Technische Dokumentation modularisieren

Transkript

1 Technische Dokumentation modularisieren Content publizieren und Varianten managen ohne CMS mit FrameMaker 11 (oder 10) Ute Mitschke tekom-ht Wiesbaden, 06. & Ute Mitschke, 03/2013

2 Wer spricht? Dipl.-Ing. Ute Mitschke 1982: Programmierung in Assembler für den ersten Z : Dozentin in der Erwachsenen-Weiterbildung : DASA: Applikationsentwicklung FrameMaker + SGML mit Prozess- und Datenanalyse 1998: DIN: Unterstützung bei der Einführung von Acrobat in allen europäischen Normungsinstituten 1999: Stiftung Warentest: Erstellung Pflichtenheft, Marktrecherche und Beratung von bei der Auswahl eines XML-basierten CMS 1999: Addison Wesley, Technische Dokumentation mit FrameMaker : Addison Wesley, FrameMaker 6+7 Praxisbuch 2003: Konzeption und Entwicklung von Katalog-Produktionen mit FM+XML seit 2004: Trainerin für Acrobat, PDFmark, FrameMaker, FM+MIF, FM+XML : Schaerer AG: Konzept und Umsetzung von Content-Management ohne CMS mit FrameMaker+XML (Schweiz) 2012/2013: HS Karlsruhe: Dozentin im Kompaktstudium Techn. Dokumentation seit 2013: Adobe Partner, selbständige Beraterin 2

3 Inhalt: Die Zielstellung für Modularisierung Analyse der Inhalte und Prozesse Anforderungen an die Lösung Modulkonzept entwickeln (Variante 1) Modulkonzept entwickeln (Variante 2) Modulkonzept verfeinern Konkretes Vorgehen in der Praxis Die Prozesse im Überblick Strukturierung der Informationen Erstellung von passenden Templates Konzeption von Metadaten Verwalten aller Module Zusammenfügen der Module zu Kapiteln Publikation eines Handbuchs Archivierung freigegebenen Handbücher Übersetzung eines Handbuchs Bei Fragen zu Modularisierung/Varianten

4 Die Zielstellung für Modularisierung Wiederverwendung von Inhalten Leichte Orientierung über die Inhalte Schnelles Wiederfinden der Module Einfache Benennung und Kennzeichnung der Module Effektive Nutzung, um Module häufig einzusetzen spezifische Publikationen zu erzeugen Übersetzungskosten zu sparen 4

5 Analyse der Inhalte und Prozesse Inhalte zur Differenzierung von Inhalten zur Differenzierung von Prozess-Zuständen zur Publikation zur Differenzierung von spez. Anforderungen Prozesse zur Informations- Erstellung/-änderung Überprüfung und Freigabe zur Publikation und Übersetzung Spez. Anforderungen 5

6 Anforderungen an die Lösung Anforderungen an Layout-Änderungen ohne manuelle Nacharbeit der Inhalte Übersetzungen konsistent durchführen und im gleichen Layout ohne Nacharbeit realisieren. spezielle Inhalte auf einfachem Weg extrahieren und wiederverwenden wiederholtes Nacharbeiten immer der selben Anforderungen komplett unnötig in verschiedenen Publikationen wiederverwenden Inhalte leicht kontrollierbar/wartbar nur einmalig übersetzen müssen 6

7 Modulkonzept entwickeln (Variante 1) Ausgangspunkt: Produkt-Palette Definition von Modulen orientiert am Produkt erfordert Analyse der Produktstruktur Identifikation aller Detail-Unterschiede anhand der Produkt-Palette Zuordnung zu Produktgruppen und klassen, Anlagenkomponenten, Optionen usw. Identifikation der Varianten-Management-Methode 7

8 Modulkonzept entwickeln (Variante 2) Ausgangspunkt: Funktionsübersicht Definition von Modulen orientiert an Funktionen erfordert Analyse der Produktstruktur und Bedienung Identifikation aller Detail-Unterschiede anhand einer Funktionsübersicht Zuordnung zu Produktgruppen und klassen, Anlagenkomponenten, Optionen usw. Identifikation der Varianten-Management-Methode 8

9 Modulkonzept verfeinern Differenzierung: nach Zielgruppe nach Publikationsart (z.b. Betriebs-/Service-Anleitung, Dialoge der Anlagensteuerung, Produktdatenblätter) nach Publikationsinhalten (Handlungsanweisung, Wartungintervalle, Stücklisten) nach Umfang der zu unterscheidenden Inhalte (einzelne Werte/Wörter, Absätze, Kapitel) nach Ziel-Medium (Webseite, Print-PDF, OnlineHilfe-CHM, App, Audio ) 9

10 Konkretes Vorgehen in der Praxis Start mit konkreten Publikationen von einem Handbuchtyp - nur Betriebsanleitungen oder nur Service-Anleitungen usw. einer Produktgruppe mehrere Anleitungen komplett ausdrucken Start mit dem Vergleich des Inhaltsverzeichnisses Notieren der Unterschiede in den Kapiteln 10

11 Konkretes Vorgehen in der Praxis (2) Seitenweise die Inhalte gleicher Kapitel vergleichen: Inhalte nach Gültigkeit erkennen: für alle Produkte (A), für eine Produktklasse (K) oder für eine Produktgruppe (G) oder für ein spezielles Produkt (P). 11

12 Konkretes Vorgehen in der Praxis (3) Abschnitte mit gleichem oder vergleichbarem Inhalt markieren identifizieren, zu welcher Inhaltsstruktur der Abschnitt gehört: Titel mit Einleitung/Summary Anweisungsblock Erklärungsblock Sicherheitshinweis technische Daten-Übersicht 12

13 Die Prozesse im Überblick Strukturierung der Informationen in FrameMaker- Dokumenten Konzeption einer Ablagestruktur Konzeption einer Benennung der Modul-Dateinamen Konzeption von Metadaten Verwalten aller Module Zusammenfügen der Module zu Kapiteln für eine konkrete Ausgabe Archivieren freigegebener Handbücher Übersetzen von Modul-Inhalten 13

14 Strukturierung der Informationen Die Strukturierung der Informationen in FrameMaker- Dokumenten kann realisiert werden: durch Format-Namen, die sich am Inhalt der Information orientieren oder durch eine XML-Struktur-Definition. Die Strukturierung der Inhalte ermöglicht es, einerseits die Formatierung leicht und gezielt anzupassen und weiterhin spezielle Inhalte aus den Modulen zu extrahieren und in anderer Form zu publizieren. Außerdem können inhaltlich differenziert formatierte Module mithilfe von Konvertierungstabellen nach XML überführt werden. 14

15 Erstellung von passenden Templates Modul-Template neutral ohne Seitenlayout der Publikation ohne fortlaufende Nummerierung Produktbezug nur in Metadaten oder in benutzerdefinierten Variablen Publikations-Template definiert das Layout der Ausgabe Unterschiedliches Layout ist möglich Enthält die konkreten Angaben zum Projekt, Handbuch, Produkt, Sprache, Version usw. 15

16 Konzeption von Metadaten Beschreibung des Inhalts, um auch bei kleinen Fragmenten den Inhalt eindeutig zuordnen zu können Angabe des Status der Bearbeitung, z.b. In Bearbeitung redaktionell geprüft fachlich geprüft freigegeben veraltet Kennzeichnung des Ursprung des Moduls Angabe einer Versionsnummer für das Modul.... weitere entsprechend den Prozessanforderungen 16

17 Verwalten aller Module Bei der Modularisierung entstehen viele FrameMaker-Dokument-Fragmente tief verschachtelt in der Ablagestruktur FrameMaker-Buch zum Verwalten der Module Module können direkt aus dem Buch geöffnet werden in allen Modulen können so leicht Formate ergänzend importiert werden Informationen über den aktuellen Bearbeitungszustand aller Module in einem Verzeichnis übersichtlich generiert werden 17

18 Zusammenfügen der Module zu Kapiteln Es sind verschiedene Methoden möglich Erstellen eines Master-Handbuchs für jeden Handbuchtyp Pro Kapitel ein leeres Kapitel-Dokument in jedem Kapitel-Dokument werden alle Module in allen Varianten in der passenden Reihenfolge als Texteinschub referenziert. Zusammenstellen von Stücklisten und Listen mit Modul-Dateinamen und Definition einer Reihenfolge Script-basiertes Zusammenstellen von speziellen Ausgaben für konkrete Produkte 18

19 Publikation eines Handbuchs Master-Handbuch-Variante Master-Handbuch und Kapitel-Dateien kopieren Kapitel öffnen und alle nicht zutreffenden Varianten löschen (Script-basiert oder manuell) Inhaltsverzeichnis erzeugen Inhalte aktualisieren und ausgeben Stücklisten-Zusammenstellung benötigte Listen zusammenstellen, Script ausführen Inhalte auf Richtigkeit und Vollständigkeit überprüfen 19

20 Archivierung freigegebenen Handbücher Kopie eines Handbuchs und aller enthaltenen Kapitel erstellen. In den Kapiteln die referenzierten Texteinschübe in Text umwandeln In den Kapiteln alle referenzierten Abbildungen als Kopie einfügen kann manuell oder Script-basiert umgesetzt werden 20

21 Übersetzung eines Handbuchs Voraussetzung ist ein entsprechender Aufbau der Modulablage Moduldateinamen müssen in allen Sprachversionen den selben Dateinamen haben, um die Kapitel- Dokumente der Quell-Sprachen-Ausgabe für alle Sprachen wiederverwenden zu können Aufgaben an den Übersetzungsprozess Identifizieren der Module zur Übersetzung Erstellen einer Voransicht für den Übersetzer Export der Module aus der Ablagestruktur Import der Module in die Zielsprachen-Ablage 21

22 Automatisieren der Publikation Methode 1: Produkt-Palette Zusammenstellung der Module mit allen Varianten in Kapitel-Dokumenten eines Master-Buchs Automatisches Entfernen nicht zutreffender Varianten Methode 2: Funktionsübersicht Zusammenstellen von Funktions-Stücklisten Zuordnung von Funktions-Varianten zu einer Funktions-Reihenfolge Erstellen einer Dokumentation aus den Konfigurations-Listen 22

23 Arbeitsblatt 1 Diskutieren Sie gemeinsam, welche Bezeichnungen für die varianten Module eingesetzt werden könnten. 23

24 Arbeitsblatt 2 Um automatisch Module zu einer Publikation zusammenzufügen, müssen die Module zusätzlich gekennzeichnet werden. Welche Metadaten müssten dafür ergänzt werde. Welche Informationen werden benötigt, um die Module in der passenden Reihenfolge automatisiert zusammen zu stellen? 24

25 Demonstration anhand eines Beispiels weiter geht es in FrameMaker 11 Arbeiten mit FrameMaker 7 bis 10 ist möglich Script-Unterstützung ab FrameMaker 10 Viele weitere Vorteile mit FrameMaker 11 25

26 Bei Fragen zu Modularisierung/Varianten tekom-website mit vielen Informationen Masterarbeiten und Unterrichtsunterlagen von Hochschulen/Universitäten Produktunterlagen von CMS-Herstellern Consulting, Workshops und Scripte für die konkrete Umsetzung gern bei mir 26

27 Vielen Dank für Ihre Aufmerksamkeit! Bitte füllen Sie die Bewertungsbogen aus. CM9 Publikationstechnologien Ute Mitschke Dipl.-Ing. (TU) Consulting & Training Konzeption & Umsetzung Informations-Design XML, FrameMaker, Acrobat TR/TD, CMS, Kataloge Adobe Partner Münchener Straße 35a Weilheim Tel.: Mobil: info@ute-mitschke.de 27

28

29

30

31

32

33