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.

Transcript

1. .consulting .solutions .partnership
   Gesunde Dokumentation mit Asciidoctor
   Alexander Schwartz, Principal IT Consultant
   Entwicklertag Karlsruhe 2016
   

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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[]
    }
    }
    

    View Slide

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[]
    }
    }
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide