Gesunde Dokumentation mit Asciidoctor (Pecha Kucha)

Gesunde Dokumentation mit Asciidoctor (Pecha Kucha)

Autoren möchten Inhalte effizient dokumentieren und vorhandene Inhalte wiederverwenden. Ein Leser möchte das Dokument in einem ansprechenden Layout präsentiert bekommen.

Das textbasierte Asciidoc-Format bietet für einen Entwickler oder technischen Redakteur alle notwendigen Auszeichungselemente, um auch anspruchsvolle Dokumente zu schreiben. So werden unter anderem Tabellen, Fußnoten und annotierte Quellcodes unterstützt. Gleichzeitig ist es ähnlich leichtgewichtig wie z.B. das Markdown Format. Für die Leser wird HTML, PDF oder EPUB generiert.

Da Asciidoc wie Programmcode eingecheckt wird und Merge-Operationen einfach möglich sind, können Programmcode und Dokumentation zusammen versioniert und auf einem einheitlichen Stand gehalten werden.

Der Vortrag gibt eine kurze Einführung in Asciidoc und die dazugehörigen Werkzeuge.

5f528a3f6814d28b583f31842e3e8d9e?s=128

Alexander Schwartz

June 15, 2016
Tweet

Transcript

  1. .consulting .solutions .partnership Gesunde Dokumentation mit Asciidoctor Alexander Schwartz, Principal

    IT Consultant Entwicklertag Karlsruhe 2016
  2. Werkzeug + – Office-Paket Gesunde Dokumentation mit Asciidoctor Womit schreibe

    ich meine Dokumentation? © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 2
  3. Werkzeug + – Office-Paket Wiki Gesunde Dokumentation mit Asciidoctor Womit

    schreibe ich meine Dokumentation? © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 3
  4. Gesunde Dokumentation mit Asciidoctor Womit schreibe ich meine Dokumentation? ©

    msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 4 Werkzeug + – Office-Paket Wiki
  5. = Das ist der Titel des Dokuments == Mit der

    ersten Überschrift Text kann ganz normal mit Umlauten geschrieben werden. *Fett*, _kursiv_ und `monospace` funktionieren wie z. B. von Markdown gewohnt. Eine Leerzeile leitet einen neuen Paragraphen ein. Damit kann es einfach mit dem Code eingecheckt werden. So sieht Asciidoc aus 1. http://asciidoctor.org/docs/asciidoc-writers-guide/ Asciidoc ist eine Textdatei © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 5
  6. = Das ist der Titel des Dokuments == Mit der

    ersten Überschrift Text kann ganz normal mit Umlauten geschrieben werden. *Fett*, _kursiv_ und `monospace` funktionieren wie z. B. von Markdown gewohnt. Eine Leerzeile leitet einen neuen Paragraphen ein. Damit kann es einfach mit dem Code eingecheckt werden. So sieht Asciidoc aus 1. http://asciidoctor.org/docs/asciidoc-writers-guide/ Asciidoc ist eine Textdatei © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 6
  7. . Aufzählungen . haben . Punkte und * Listen *

    haben * Sterne //// und Das ist ein Block-Kommentar //// So sieht Asciidoc aus 1. http://asciidoctor.org/docs/asciidoc-writers-guide/ Asciidoc Dokumente schreibt man wie eine Text-E-Mail © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 7
  8. [source,txt] .Dateiname der Datei ---- Ein Listing mit Syntax-Highlighting. ----

    [cols="2*", options="header"] |=== |Überschrift |Noch eine Überschrift |Text in der ersten Spalte |Text in der zweiten Spalte |=== So sieht Asciidoc aus 1. http://asciidoctor.org/docs/asciidoc-writers-guide/ Listings im Text und schöne Tabellen © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 8
  9. [source,txt] .Dateiname der Datei ---- Ein Listing mit Syntax-Highlighting. ----

    [cols="2*", options="header"] |=== |Überschrift |Noch eine Überschrift |Text in der ersten Spalte |Text in der zweiten Spalte |=== So sieht Asciidoc aus 1. http://asciidoctor.org/docs/asciidoc-writers-guide/ Listings im Text und schöne Tabellen © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 9
  10. [source,java,indent=0] .Quellcode.java ---- include::Quellcode.java[tag=wichtig] ---- <1> das ist wirklich sehr

    interessant So sieht Asciidoc aus Beispiele aus echtem, kompilierenden Code einbinden © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 10 public class Quellcode { public static void main(String argv[]) { uninteressant(); // tag::wichtig[] if(sehrInteressant()) { // <1> /* ... */ } // end::wichtig[] } }
  11. [source,java,indent=0] .Quellcode.java ---- include::Quellcode.java[tag=wichtig] ---- <1> das ist wirklich sehr

    interessant So sieht Asciidoc aus Beispiele aus echtem, kompilierenden Code einbinden © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 11 public class Quellcode { public static void main(String argv[]) { uninteressant(); // tag::wichtig[] if(sehrInteressant()) { // <1> /* ... */ } // end::wichtig[] } }
  12. .Big Picture ["plantuml", "overview", "png"] -- include::overview.puml[] -- So sieht

    Asciidoc aus 1. http://plantuml.sourceforge.net/ Diagramme im Text mit PlantUML schreiben © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 12 @startuml actor User node "Load Balancer" { [nginx] } User --> nginx @enduml
  13. .Big Picture ["plantuml", "overview", "png"] -- include::overview.puml[] -- So sieht

    Asciidoc aus 1. http://plantuml.sourceforge.net/ Diagramme im Text mit PlantUML schreiben © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 13 @startuml actor User node "Load Balancer" { [nginx] } User --> nginx @enduml
  14. Einfach geschrieben 1. https://github.com/asciidoctor/asciidoctor-intellij-plugin 2. https://github.com/esteinberg/plantuml4idea IDE-Support: IntelliJ IDEA ©

    msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 14
  15. Einfach geschrieben 1. http://asciidocfx.com/ IDE-Support: AsciidocFX © msg | Juni

    2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 15
  16. Einfach geschrieben 1. https://atom.io/ IDE-Support: Atom © msg | Juni

    2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 16
  17. Automatisch erstellt 1. http://danhyun.github.io/asciidoctor-gradle-examples/ Ausgabeformate sind vielfältig © msg |

    Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 17 REVEAL.JS PDF
  18. Kommandozeile (Ruby/JRuby) asciidoctor -r asciidoctor-diagram sample.adoc Plugins für: Automatisch erstellt

    Dokumentation als Teil von Continuous Integration © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 18
  19. Spring (12/2013): “We recently migrated all of our Getting Started

    Guides to Asciidoctor. Why? Because Asciidoctor provides so many valuable features!” Geb (06/2015) “Migration of the Book of Geb to @asciidoctor with executable examples has been completed” http://www.gebish.org/manual/current/ O’Reilly, MakerPress, Git user manual, … https://git-scm.com/documentation Arc42 https://github.com/arc42/arc42-template Gesunde Dokumentation mit Asciidoctor 1. https://spring.io/blog/2013/12/13/spring-s-getting-started-guides-migrated-to-asciidoctor 2. https://twitter.com/gebframework/status/614407603620327424 3. https://github.com/asciidoctor/asciidoctor.org/issues/270 Große Projekte haben umgestellt … was ist mit dir? © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 19
  20. Gesunde Dokumentation mit Asciidoctor Große Projekte haben umgestellt … was

    ist mit dir? © msg | Juni 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 20 @ahus1de
  21. .consulting .solutions .partnership Alexander Schwartz Principal IT Consultant +49 171

    / 5625767 alexander.schwartz@msg-systems.com @ahus1de msg systems ag (Headquarters) Robert-Buerkle-Str. 1, 85737 Ismaning Germany www.msg-systems.com