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 Workshop 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.

Transcript

1. Einstieg in Documentation-as-Code
   mit AsciiDoc®
   Alexander Schwartz, Principal Software Engineer, Red Hat
   tekom Frühjahrstagung, Würzburg, 2023-04-27
   

   View Slide

2. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 2
   Dokumentation in der IDE schreiben? Klar, mit AsciiDoc!
   Ausgangspunkt
   1.
   AsciiDoc als Sprache
   2.
   AsciiDoc zum selber ausprobieren
   3.
   Zusammenfassung
   4.
   

   View Slide

3. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 3
   Womit soll ich meine technische Dokumentation schreiben?
   Motivation
   Ich habe schon mal gearbeitet mit: Das hat gut geklappt: Das hat weniger gut geklappt:
   

   View Slide

4. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 6
   Dokumentation in der IDE schreiben? Klar, mit AsciiDoc!
   Ausgangspunkt
   1.
   AsciiDoc als Sprache
   2.
   AsciiDoc zum selber ausprobieren
   3.
   Zusammenfassung
   4.
   

   View Slide

5. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 7
   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
   

   View Slide

6. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 8
   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
   https://asciidoc-wg.eclipse.org/
   

   View Slide

7. • Dokumente ohne Ablenkung in der
   Entwicklungsumgebung schreiben
   • Kollaboration und Versionierung mit Git
   • Vorlagen liefern Hilfen und Struktur
   • Nahtloses Einbinden in Continuous
   Delivery Prozesse
   CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 9
   Technische Dokumentation als Teil des Entwicklungsprozesses
   Liste der Editoren:
   https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
   

   View Slide

8. IDE-Unterstützung inklusive Preview ist verfügbar als Plugin für alle großen IDEs, zum Beispiel:
   • IntelliJ IDEA (inklusive WebStorm, RubyMine, PyCharm, GoLand, etc.)
   • Eclipse IDE
   • Visual Studio Code
   • Brackets
   Vorschau ist verfügbar:
   • via Browser Extensions für Firefox, Opera und Chrome
   Eigenständiger Editor:
   • Asciidoc FX
   CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 10
   IDE-Unterstützung für AsciiDoc
   Source:
   https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
   

   View Slide

9. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 11
   Dokumentation in der IDE schreiben? Klar, mit AsciiDoc!
   Ausgangspunkt
   1.
   AsciiDoc als Sprache
   2.
   AsciiDoc zum selber ausprobieren
   3.
   Zusammenfassung
   4.
   

   View Slide

10. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 12
    Web Editor mit Live Preview
    AsciiDoc zum selber ausprobieren
    Scratch
    Liste Quellcode
    Vorschau
    

    View Slide

11. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 13
    Übungsaufgaben für die Gruppenarbeit
    AsciiDoc zum selber ausprobieren
    Formatieren
    von Text
    Verwenden
    von Listen
    Erstellen
    von Tabellen
    Bilder und
    Diagramme
    Strukturieren
    von Dokumenten
    Einbinden von
    Quellcode
    

    View Slide

12. Each sentence should be in a separate line.
    Every blank line creates a new paragraph.
    You can write *bold* text.
    _Italic_ works as well text.
    Lists
    . work
    . with
    . dots
    to make them numbered and
    * asterisks
    * to
    * make
    bullet points.
    CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 14
    Texte und Listen
    AsciiDoc zum selber ausprobieren
    

    View Slide

13. [IMPORTANT]
    --
    You can mark a paragraph to be important.
    --
    TIP: There is also the shorter one-line-
    syntax.
    ====
    This is an example block. Use it to
    provide examples to your users.
    ====
    ----
    This is a listing.
    You can provide syntax highlighting for
    XML/Java etc. here.
    ----
    CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 15
    Abschnitte und Auszeichnungen
    AsciiDoc zum selber ausprobieren
    

    View Slide

14. Tables are blocks, `|===` marks their
    beginning and end.
    .Table title
    [cols="1,1,3a,1"]
    |===
    |H1 |H2 |H3 |H4
    |Cell 1
    |Cell 2
    |Formatting *of words* works like in
    _before_ if you switch the column or
    cell to AsciiDoc format.
    |Cell 4
    |===
    CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 16
    Tabellen
    AsciiDoc zum selber ausprobieren
    

    View Slide

15. Images can be in-line and as blocks.
    An image:file.svg[pdfwidth=3cm] image in-
    line.
    An image with a caption:
    .This is an image
    image::file.svg[]
    For schematic drawings prefer to use SVG
    images for best results on the Web and in
    PDFs.
    CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 17
    Bilder
    AsciiDoc zum selber ausprobieren
    

    View Slide

16. To store diagrams as text, have a look at
    PlantUML:
    .Diagrams can have a caption as well.
    plantuml::showcase_swimlanes.puml[swimlanes,svg]
    CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 18
    Grafiken am Beispiel PlantUML
    AsciiDoc zum selber ausprobieren
    @startuml
    skinparam shadowing false
    |Component with Web-UI|
    start
    :User opens web page;
    :Forward to authentication;
    |#AntiqueWhite|Authentication|
    :Authenticate with user name\nand password;
    :Forward to Web-UI;
    |Component with Web-UI|
    :Open Web-UI;
    stop
    @enduml
    

    View Slide

17. .Standard include
    [source,java]
    ----
    include::Example.java[]
    ----
    :icons: font
    .Pick a block with callout
    [source,java,indent=0]
    ----
    include::Example.java[tag=sop]
    ----
    <1> this is your first line of Java
    CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 19
    Quellcode-Beispiele einbinden
    AsciiDoc zum selber ausprobieren
    

    View Slide

18. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 20
    Dokumentation in der IDE schreiben? Klar, mit AsciiDoc!
    Ausgangspunkt
    1.
    AsciiDoc als Sprache
    2.
    AsciiDoc zum selber ausprobieren
    3.
    Zusammenfassung
    4.
    

    View Slide

19. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 21
    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
    https://asciidoc-wg.eclipse.org/
    

    View Slide

20. 22
    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
    CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz
    AsciiDoc fördert Zusammenarbeit, De-Duplikation und Automatisierung
    

    View Slide

21. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 23
    Technische Dokumentation mit AsciiDoc erstellen
    Blick nach vorn
    Das hat mich begeistert: Darüber möchte ich mehr erfahren: Das probiere ich nächste Woche aus:
    

    View Slide

22. CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 24
    Einstieg in Documentation-as-Code mit AsciiDoc
    https://jahrestagung.tekom.de/tagungsprogramm/bewertung/einstieg-in-documentation-as-code-mit-asciidoc
    Ihre Bewertung hilft, diesen Workshop weiterzuentwickeln und ihn ggf. an anderer Stelle zu
    wiederholen. Vielen Dank!
    

    View Slide

23. AsciiDoc Kata
    https://github.com/ahus1/asciidoc-kata
    AsciiDoc Language
    https://asciidoc.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/
    CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 25
    Links
    @ahus1de
    Antora
    https://antora.org/
    Videos, Folien und Beispiele
    https://ahus1.de/post/asciidoctor-intro-and-deep-dive
    Udemy: Technical Writing with AsciiDoc and IntelliJ IDEA
    https://ahus1.de/post/technical-writing-udemy
    

    View Slide

24. Kontakt
    Alexander Schwartz
    Principal Software Engineer
    +49 172 6752068
    alexander.schwartz@gmx.net
    @ahus1de
    CC BY-NC-SA 4.0 | April 2023 | Einstieg in Documentation-as-Code mit AsciiDoc® | Alexander Schwartz 26
    

    View Slide