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
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.
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:
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.
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
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/
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/
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/
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.
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
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
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
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
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
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
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
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
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.
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/
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
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:
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!
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
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