Sonnenfinsternis in der Technischen Redaktion

Transkript

1 Sonnenfinsternis in der Technischen Redaktion Eclipse-basierte Tools für die Software-Dokumentation Frank Ralf parson AG tekom-jahrestagung

2 Agenda Eclipse-basierte Tools für die Softwaredokumentation Warum Eclipse? In Eclipse Dokumentation im Code und manuell Raus aus Eclipse Dokumentation konvertieren und exportieren Rein in Eclipse Dokumentation in Eclipse integrieren Außerhalb von Eclipse separate Tools auf Basis von Eclipse Diskussion November 2014 Sonnenfinsternis in der Technischen Redaktion 2

3 Motivation Problem: Entwickler dokumentieren nicht gern. Wir als Technische Redakteure können helfen. Beidseitiger Gewinn: Entwickler in gewohnter Umgebung einfacher zur Software- Dokumentation beitragen Technischer Redakteur vielfältige Funktionen von Eclipse selber nutzen November 2014 Sonnenfinsternis in der Technischen Redaktion 3

4 Das werden wir behandeln: Javadoc Dokumentation direkt im Quellcode API-Doku automatisch als HTML generieren Mylyn WikiText Dokumentation in unterschiedlichen leichtgewichtigen Markup-Sprachen schreiben Dokumentation konvertieren und exportieren: EPUB, DITA, DocBook, HTML etc. Eclipse Help Dokumentation in Eclipse einbinden Eclipse-basierte Tools für die Dokumentation IBM Information Architecture Workbench November 2014 Sonnenfinsternis in der Technischen Redaktion 4

5 Nur am Rande hingegen: Funktionen von Eclipse, die nicht unmittelbar mit Dokumentation zu tun haben (aber auch für Technische Redakteure durchaus interessant sein können): Versionskontrolle (Git, Subversion, CVS) Task Management (Mylyn Task) Anbindung an Trackingsysteme (Bugzilla, Jira) DITA und Eclipse Sascha Kuchar "Der Redaktionsprozess mit Eclipse und DITA" DITA11, Do 15:30-16:15, Raum C1.2.1 / Plenum EG November 2014 Sonnenfinsternis in der Technischen Redaktion 5

6 Wer sind Sie? Wer ist Entwickler? Wer ist Technischer Redakteur? Wer hat schon mit Eclipse gearbeitet? November 2014 Sonnenfinsternis in der Technischen Redaktion 6

7 1. Eclipse Info November 2014 Sonnenfinsternis in der Technischen Redaktion 7

8 Warum Eclipse? Integrierte Entwicklungsumgebung (IDE) am weitesten verbreitete IDE Unterstützung durch die Industrie Open Source offen kostenlos erweiterbar Plattform für selbständige Anwendungen oxygen XML Editor IBM Information Architecture Workbench (IAWB) Requirement Management Framework (RMF) November 2014 Sonnenfinsternis in der Technischen Redaktion 8

9 Loslegen mit Eclipse Download Installation Erweiterungen installieren Updates Integrierte Hilfe November 2014 Sonnenfinsternis in der Technischen Redaktion 9

10 Eclipse herunterladen November 2014 Sonnenfinsternis in der Technischen Redaktion 10

11 Welcome Screen November 2014 Sonnenfinsternis in der Technischen Redaktion 11

12 Etwas Eclipse-Jargon Workspace: zentraler Speicherort für Projekte View: zur Anzeige von Daten und Informationen Editor: zum Bearbeiten von Daten Perspective: Gesamtlayout aus allen Views, Editoren bleiben unabhängig davon erhalten Workbench: aktueller Arbeitsbereich November 2014 Sonnenfinsternis in der Technischen Redaktion 12

13 1. Eclipse Demo November 2014 Sonnenfinsternis in der Technischen Redaktion 13

14 Eclipse Workbench November 2014 Sonnenfinsternis in der Technischen Redaktion 14

15 JSweeper als Beispiel November 2014 Sonnenfinsternis in der Technischen Redaktion 15

16 JSweeper herunterladen November 2014 Sonnenfinsternis in der Technischen Redaktion 16

17 JSweeper importieren November 2014 Sonnenfinsternis in der Technischen Redaktion 17

18 2. Javadoc Info November 2014 Sonnenfinsternis in der Technischen Redaktion 18

19 2. Javadoc Beispiele November 2014 Sonnenfinsternis in der Technischen Redaktion 19

20 2. Javadoc Demo November 2014 Sonnenfinsternis in der Technischen Redaktion 20

21 Javadoc View November 2014 Sonnenfinsternis in der Technischen Redaktion 21

22 Javadoc Preferences November 2014 Sonnenfinsternis in der Technischen Redaktion 22

23 Javadoc-Warnungen November 2014 Sonnenfinsternis in der Technischen Redaktion 23

24 Javadoc Generation November 2014 Sonnenfinsternis in der Technischen Redaktion 24

25 3. Mylyn WikiText Info November 2014 Sonnenfinsternis in der Technischen Redaktion 25

26 Eclipse Mylyn November 2014 Sonnenfinsternis in der Technischen Redaktion 26

27 Tasktop Mylyn November 2014 Sonnenfinsternis in der Technischen Redaktion 27

28 Mylyn Docs November 2014 Sonnenfinsternis in der Technischen Redaktion 28

29 Mylyn WikiText November 2014 Sonnenfinsternis in der Technischen Redaktion 29

30 Unterschiedliche Syntax November 2014 Sonnenfinsternis in der Technischen Redaktion 30

31 identische Darstellung November 2014 Sonnenfinsternis in der Technischen Redaktion 31

32 WikiText konvertieren November 2014 Sonnenfinsternis in der Technischen Redaktion 32

33 WikiText konfigurieren November 2014 Sonnenfinsternis in der Technischen Redaktion 33

34 3. Mylyn WikiText Demo November 2014 Sonnenfinsternis in der Technischen Redaktion 34

35 4. DITA generieren Info November 2014 Sonnenfinsternis in der Technischen Redaktion 35

36 DITA generieren Info Nur per Ant-Script. Verschiedene Ausgabeoptionen: topicdoctype DTD-Doctype der Ausgabedokumente topicstrategy Gibt an, wie mehrere Ausgabedateien erzeugt werden sollen FIRST mehrere Topic-Dateien, aufgeteilt nach der ersten Überschriftstufe. LEVEL1 eine DITA-Datei für jede H1-Überschrift. NONE nur eine Topic-Datei, ohne Bookmap. November 2014 Sonnenfinsternis in der Technischen Redaktion 36

37 4. DITA generieren Demo November 2014 Sonnenfinsternis in der Technischen Redaktion 37

38 5. Eclipse Help einbinden Info November 2014 Sonnenfinsternis in der Technischen Redaktion 38

39 5. Eclipse Help einbinden Demo November 2014 Sonnenfinsternis in der Technischen Redaktion 39

40 DITA > Eclipse Help November 2014 Sonnenfinsternis in der Technischen Redaktion 40

41 6. Eclipse-basierte Tools November 2014 Sonnenfinsternis in der Technischen Redaktion 41

42 6. Eclipse-basierte Tools November 2014 Sonnenfinsternis in der Technischen Redaktion 42

43 IBM Information Architecture Workbench November 2014 Sonnenfinsternis in der Technischen Redaktion 43

44 Requirement Management Framework (RMF) November 2014 Sonnenfinsternis in der Technischen Redaktion 44

45 formalmind Studio November 2014 Sonnenfinsternis in der Technischen Redaktion 45

46 Beidseitiger Gewinn: Fazit Entwickler in gewohnter Umgebung einfacher zur Software- Dokumentation beitragen Technischer Redakteur vielfältige Funktionen von Eclipse selber nutzen November 2014 Sonnenfinsternis in der Technischen Redaktion 46

47 Literaturtipps Ed Burnette, Jörg Staudemeyer Eclipse IDE kurz & gut O Reilly, 3. Auflage 2013 Lars Vogel Eclipse IDE Version 4.5 ( ) November 2014 Sonnenfinsternis in der Technischen Redaktion 47

48 Weitere Informationen GitHub Technischen-Dokumentation November 2014 Sonnenfinsternis in der Technischen Redaktion 48

49 Diskussion November 2014 Sonnenfinsternis in der Technischen Redaktion 49

50 Frank Ralf Feedback Ihre Meinung ist uns wichtig! Sagen Sie uns bitte, wie Ihnen der Vortrag gefallen hat. Wir freuen uns auf Ihr Feedback per Smartphone oder Tablet unter oder scannen Sie den QR-Code Das Bewertungstool steht Ihnen auch noch nach der Tagung zur Verfügung! 50

51 Frank Ralf parson AG Chrysanderstr. 69 A Hamburg +49 (0) contact@parson-europe.com