AsciiDoc Deep Dive (Deutsch)

Mit AsciiDoc kann Dokumentation im gleichen Repository wie der Quellcode des Programms eingecheckt werden. Damit kann die Dokumentation in AsciiDoc zusammen mit der Funktionalität im Code mit jeder umgesetzten User-Story mitwachsen.

Für IDEs gibt es Plug-ins, die eine Vorschau für die erstellten Texte ermöglichen und Refactorings der erstellten Dokumente erlauben. Der Continuous-Integration-Server erstellt anschließend aus den AsciiDoc-Dateien die HTML- oder PDF-Dokumente für die Nutzer.

Ihr habt schon erste Erfahrungen mit AsciiDoc gesammelt und wollt mehr erfahren?

Dieser Vortrag geht in die Details und beantwortet folgende Fragen:

* Wie strukturiere ich große Dokumente?
* Wie kann ich mit PlantUML schönere Grafiken erzeugen?
* Wie binde ich Quellen ein und nutze Querverweise?
* Was ist im Styling von PDFs möglich?
* Wie funktioniert Silbentrennung?
* Wie kann mich meine IDE unterstützen?

Transcript

1. AsciiDoc® Deep Dive Alexander Schwartz, Principal Software Engineer @ Red Hat betterCode() ArchDoc | 2023-06-26
2. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 2 AsciiDoc Deep Dive Motivation 1 Demo AsciiDoc Syntax und Ökosystem 2 Demo Asciidoctor PDF-Erzeugung 3 Zusammenfassung 4
3. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 3 AsciiDoc Deep Dive Motivation 1 Demo AsciiDoc Syntax und Ökosystem 2 Demo Asciidoctor PDF-Erzeugung 3 Zusammenfassung 4
4. Tool + – Office-Suite CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 4 Was nutzt ihr, um Dokumente zu schreiben? Motivation
5. Tool + – Office-Suite Wiki CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 5 Was nutzt ihr, um Dokumente zu schreiben? Motivation
6. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 6 Möglichkeiten in einer Continuous Integration/Delivery-Umgebung Motivation Code Snippets Publizieren (auf Website) Druckbare Dokumentation Änderungen verfolgen Suchen in Documentation De-Duplikation und Wiederverwendung Text APIs Diagramme Tests Share Merge
7. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | 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 https://asciidoc-wg.eclipse.org/
8. • 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 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 8 Technische Dokumentation als Teil des Entwicklungsprozesses Liste der Editoren: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
9. Asciidoctor Deep Dive CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 9 Motivation 1 Demo AsciiDoc Syntax und Ökosystem 2 Demo Asciidoctor PDF-Erzeugung 3 Zusammenfassung 4
10. Features: • Variablen, Listen, Referenzen, Tabellen • Bedingte Formatierung • Listings, mathematische Formeln, Icons • Diagramme mit PlantUML • Erweiterungen • Unterstützung für Spring REST Docs CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 10 Demo AsciiDoc und IDE Unterstützung
11. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 11 Demo AsciiDoc Syntax und Ökosytem Texte und Listen 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.
12. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 12 Demo AsciiDoc Syntax und Ökosytem Abschnitte und Auszeichnungen [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. ----
13. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 13 Demo AsciiDoc Syntax und Ökosytem Tabellen 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 |===
14. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 14 Demo AsciiDoc Syntax und Ökosytem Bilder 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.
15. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 15 Demo AsciiDoc Syntax und Ökosytem Grafiken am Beispiel PlantUML To store diagrams as text, have a look at PlantUML: .Diagrams can have a caption as well. plantuml::showcase_swimlanes.puml[swimlanes,svg] @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
16. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 16 Demo AsciiDoc Syntax und Ökosytem Quellcode-Beispiele einbinden .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
17. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 17 Pipeline für Dokumentation mit docToolchain Source: https://doctoolchain.github.io/docToolchain/
18. 18 Source: https://doctoolchain.github.io/docToolchain/
19. 19 Dokumentation unterstützt die Nutzer bei ihrer Arbeit Warum AsciiDoc und Antora • Online, automatisiert, aktuell • Durchsuchbar and themen-basiert • Navigation und Querverweise • Gruppiert nach Version und Komponente CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz
20. 20 Antora liefert Struktur und Werkzeuge zur Automatisierung • Strukturiert Dokumentation in Komponenten und Module • Sammelt AsciiDoc-Inhalte aus verschiedenen Git-Repositories und Branches • Konvertiert AsciiDoc Inhalte in HTML • Verbindet das HTML mit dem UI Theme und erzeugt eine statische Web-Site Hauptvorteile: • Schnelle Konvertierung auf Basis von Node.js mit wenigen abhängigen Modulen • Modular und erweiterbar CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz
21. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 21 Asciidoctor Deep Dive Motivation 1 Demo AsciiDoc Syntax und Ökosystem 2 Demo Asciidoctor PDF-Erzeugung 3 Zusammenfassung 4
22. • Template auswählen • Kopf- und Fußzeile konfigurieren • Titelseite definieren • Übergabe von Attributen z. B. via Maven • Silbentrennung CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 22 Demo PDF Erstellung mit Prawn/Asciidoctor PDF Source: https://asciidoctor.org/docs/asciidoctor-pdf/ https://github.com/asciidoctor/asciidoctor-pdf/issues/20 https://github.com/ahus1/asciidoctor-deepdive/tree/master/manual
23. • Bestehende Templates vs. individuelle Templates • Design mittels CSS • Basiert auf JavaScript, automatisierbar mit yarn/npm • Individuelle Layouts (zum Beispiel mit Spalten) CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 23 Demo PDF Erstellung mit Puppeteer/Asciidoctor Web PDF Source: https://github.com/Mogztter/asciidoctor-pdf.js/tree/master/examples/cheat-sheet
24. Source: https://github.com/Mogztter/asciidoctor-pdf.js/tree/master/examples/cheat-sheet CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 24
25. 25 Warum AsciiDoc Aktuelle und korrekte Inhalte durch Zusammenarbeit als Team über die Versionsverwaltung intelligente IDEs Konsistenz über verschiedene Dokumente hinweg durch Publikation von verschiedenen Formaten wie HTML und PDF, De-Duplikation und Wiederverwendung Lieferung neuer Funktionen inklusive Dokumentation durch automatisierte Erstellung der Dokumente oder als Teil von Websites CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz AsciiDoc fördert Zusammenarbeit, De-Duplikation und Automatisierung
26. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 26 Asciidoctor Deep Dive Motivation 1 Demo AsciiDoc Syntax und Ökosystem 2 Demo Asciidoctor PDF-Erzeugung 3 Zusammenfassung 4
27. CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 27 AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung 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/ Asciidoctor https://asciidoctor.org/
28. AsciiDoc https://asciidoc.org Asciidoctor https://asciidoctor.org IntelliJ AsciiDoc Plugin https://ahus1.de/post/technical-writing-udemy PlantUML http://plantuml.com/ https://real-world-plantuml.com/ docToolchain https://doctoolchain.github.io/docToolchain/ Links CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 28 @ahus1de Asciidoctor Web PDF https://github.com/ggrossetie/asciidoctor-web-pdf Documentation as Code mit Asciidoctor https://heise.de/-4642013 Antora https://antora.org/ https://www.ahus1.de/post/documentation-site-antora Video, Folien und Beispiele https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive @ahus1@fosstodon.org
29. Kontakt Alexander Schwartz Principal Software Engineer alexander.schwartz@gmx.net https://www.ahus1.de @ahus1de @ahus1@fosstodon.org CC BY-NC-SA 4.0 | Juni 2023 | AsciiDoc® Deep Dive | Alexander Schwartz 29