Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Gesunde Dokumentation mit Asciidoctor

Gesunde Dokumentation mit Asciidoctor

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.

Alexander Schwartz

March 08, 2016
Tweet

More Decks by Alexander Schwartz

Other Decks in Technology

Transcript

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

    View Slide

  2. Werkzeug Positiv Negativ
    Office-Paket • Drucken
    • Weitergeben
    • Offline bearbeiten
    • Versionieren mit
    Code/Programmversion
    • Online verfügbar
    • Änderungen
    zusammenführen
    Wiki • Online verfügbar
    • Jeder kann die
    Dokumentation ändern
    • Zusammengehörigkeit zu
    einer Programmversion
    • Drucken
    • Weitergeben
    • Versionieren mit
    Code/Programmversion
    Gesunde Dokumentation mit Asciidoctor
    Womit schreibe ich Dokumentation und wo hebe ich sie auf?
    © msg | März 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 2

    View Slide

  3. = 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 | März 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 3

    View Slide

  4. . 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 | März 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 4

    View Slide

  5. [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/
    Tabellen und Listings im Text
    © msg | März 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 5

    View Slide

  6. [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 | März 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 6
    public class Quellcode {
    public static void main(String argv[]) {
    uninteressant();
    // tag::wichtig[]
    if(sehrInteressant()) { // <1>
    /* ... */
    }
    // end::wichtig[]
    }
    }

    View Slide

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

    View Slide

  8. Einfach geschrieben
    1. https://github.com/asciidoctor/asciidoctor-intellij-plugin
    2. https://github.com/esteinberg/plantuml4idea
    IDE-Support: IntelliJ IDEA
    © msg | März 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 8

    View Slide

  9. Einfach geschrieben
    1. http://asciidocfx.com/
    IDE-Support: AsciidocFX
    © msg | März 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 9

    View Slide

  10. Einfach geschrieben
    1. https://atom.io/
    IDE-Support: Atom
    © msg | März 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 10

    View Slide

  11. Automatisch erstellt
    1. http://danhyun.github.io/asciidoctor-gradle-examples/
    Ausgabeformate sind vielfältig
    © msg | März 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 11
    REVEAL.JS
    PDF

    View Slide

  12. Kommandozeile (Ruby/JRuby)
    asciidoctor -r asciidoctor-diagram sample.adoc
    Plugins für:
    Automatisch erstellt
    Dokumentation als Teil von Continuous Integration
    © msg | März 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 12

    View Slide

  13. 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 | März 2016 | Gesunde Dokumentation mit Asciidoctor | Alexander Schwartz 13
    @ahus1de

    View Slide

  14. .consulting .solutions .partnership
    Alexander Schwartz
    Principal IT Consultant
    +49 171 / 5625767
    [email protected]
    @ahus1de
    msg systems ag (Headquarters)
    Robert-Buerkle-Str. 1, 85737 Ismaning
    Germany
    www.msg-systems.com

    View Slide