Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Dokumentation in der IDE schreiben - mit AsciiDoc

5f528a3f6814d28b583f31842e3e8d9e?s=47 Alexander Schwartz
December 09, 2020
13

Dokumentation in der IDE schreiben - mit AsciiDoc

Die Prinzipien von Documentation-as-Code sind erfüllt, wenn für die Erstellung von Dokumentation die normale Entwicklungsumgebung genutzt wird, Zusammenarbeit und Reviews über die Versionsverwaltung erfolgen und der Continuous-Integration-Server nicht nur die Software, sondern auch die Dokumentation baut. Im Gegensatz zu Office-Dokumente oder Wikis ist Dokumentation so in den normalen Entwicklungs- und Review-Prozess integriert. AsciiDoc ist eine leichtgewichtige Markup-Sprache, aus der automatisiert zum Beispiel HTML- oder PDF-Dokumente erstellt werden können. In der Entwicklungsumgebung sorgen Plugins für ein Schreiben mit Vorschau-Fenster. Bei jedem Commit in der Versionsverwaltung wird nicht nur die Funktionalität des Programms weitergeschrieben, sondern auch die Architektur-, Entwicklungs- oder Benutzerdokumentation.

Dies ist ein Vortrag für Einsteiger: Nach einer kurzen Einführung zu AsciiDoc setzen die Teilnehmer kleine Texte in AsciiDoc unter Anleitung des Vortragenden um. Hierbei kommt eine Web-IDE zum Einsatz, so dass die Teilnehmer nur einen Browser für die Teilnahme benötigen.

5f528a3f6814d28b583f31842e3e8d9e?s=128

Alexander Schwartz

December 09, 2020
Tweet

Transcript

  1. Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! Alexander Schwartz,

    Principal IT Consultant IT Tage Frankfurt, 2020-12-09
  2. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz 2 Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! Motivation 1. AsciiDoc als Sprache 2. Demo AsciiDoc Syntax und Ökosystem 3. Zusammenfassung 4.
  3. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz 3 Womit soll ich meine Dokumentation schreiben? Motivation Tool + – Office-Suite
  4. Tool + – Office-Suite Wiki © msg | Dezember 2020

    | Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! | Alexander Schwartz 4 Womit soll ich meine Dokumentation schreiben? Motivation
  5. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz 5 Möglichkeiten in einer Continuous Integration/Delivery-Umgebung Motivation Code Snippets Publizieren (auf Website) Druckbare Dokumentation Änderungen verfolgen Suchen in Dokumentation De-Duplikation und Wiederverwendung Text APIs Diagramme Tests Share Merge
  6. 6 Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! ©

    msg | Dezember 2020 | Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! | Alexander Schwartz Motivation 1. AsciiDoc als Sprache 2. Demo AsciiDoc Syntax und Ökosystem 3. Zusammenfassung 4.
  7. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz 7 AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung Asciidoctor https://asciidoctor.org/ AsciiDoc • fokussiertes Schreiben ohne Ablenkung • hat alles was technische Dokumentation benötigt • 15 Jahre alt und sehr lebendig • Standardisierung in 2020 bei Eclipse Foundation gestartet Asciidoctor • Implementierung um HTML und PDFs aus AsciiDoc- Dateien zu erzeugen • OpenSource Implementierung • Läuft mit Java, Ruby und JavaScript • kann z. B. in Maven und Gradle Builds über Plugins integriert werden AsciiDoc Eclipse Working Group
  8. • Dokumente ohne Ablenkung in der Entwicklungsumgebung schreiben • Kollaboration

    und Versionierung mit Git • Vorlagen liefern Hilfen und Struktur • Nahtloses Einbinden in Continuous Delivery Prozesse © msg | Dezember 2020 | Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! | Alexander Schwartz 8 Technische Dokumentation als Teil des Entwicklungsprozesses Liste der Editoren: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
  9. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz 10 Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! Motivation 1. AsciiDoc als Sprache 2. Demo AsciiDoc Syntax und Ökosystem 3. Zusammenfassung 4.
  10. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz Texte und Listen Demo AsciiDoc Syntax und Ökosytem 11
  11. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz Abschnitte und Auszeichnungen Demo AsciiDoc Syntax und Ökosytem 12
  12. | | | | | | | © msg |

    Dezember 2020 | Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! | Alexander Schwartz Tabellen Demo AsciiDoc Syntax und Ökosytem 13
  13. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz Bilder Demo AsciiDoc Syntax und Ökosytem 14
  14. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz Grafiken am Beispiel PlantUML Demo AsciiDoc Syntax und Ökosytem 15
  15. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz Quellcode-Beispiele einbinden Demo AsciiDoc Syntax und Ökosytem 16
  16. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz 17 Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! Motivation 1. AsciiDoc als Sprache 2. Demo AsciiDoc Syntax und Ökosystem 3. Zusammenfassung 4.
  17. © msg | Dezember 2020 | Dokumentation in der IDE

    schreiben? Klar, mit AsciiDoc! | Alexander Schwartz 18 AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung Asciidoctor https://asciidoctor.org/ AsciiDoc • fokussiertes Schreiben ohne Ablenkung • hat alles was technische Dokumentation benötigt • 15 Jahre alt und sehr lebendig • Standardisierung in 2020 bei Eclipse Foundation gestartet Asciidoctor • Implementierung um HTML und PDFs aus AsciiDoc- Dateien zu erzeugen • OpenSource Implementierung • Läuft mit Java, Ruby und JavaScript • kann z. B. in Maven und Gradle Builds über Plugins integriert werden AsciiDoc Eclipse Working Group
  18. Warum AsciiDoc Aktuelle und korrekte Inhalte durch Zusammenarbeit als Team

    über die Versionsverwaltung Konsistenz über verschiedene Dokumente hinweg durch Publikation von verschiedenen Formaten, De-Duplikation und Wiederverwendung Lieferung neuer Funktionen inklusive Dokumentation durch automatisierte Erstellung der Dokumente © msg | Dezember 2020 | Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! | Alexander Schwartz AsciiDoc fördert Zusammenarbeit, De-Duplikation und Automatisierung 19
  19. Asciidoctor https://asciidoctor.org IntelliJ AsciiDoc Plugin https://intellij-asciidoc-plugin.ahus1.de/ PlantUML http://plantuml.com/ https://real-world-plantuml.com/ docToolchain

    https://doctoolchain.github.io/docToolchain/ © msg | Dezember 2020 | Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! | Alexander Schwartz 20 Links @ahus1de Asciidoctor PDF.js https://github.com/Mogztter/asciidoctor-pdf.js Antora https://antora.org/ Videos, Folien und Beispiele https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive
  20. msg systems ag Robert-​Bürkle-Straße 1 85737 Ismaning Germany value –

    inspired by people Contact Alexander Schwartz Principal IT Consultant +49 171 5625767 alexander.schwartz@msg.group @ahus1de © msg | Dezember 2020 | Dokumentation in der IDE schreiben? Klar, mit AsciiDoc! | Alexander Schwartz 21