© Excellent backgrounds/Shutterstock.com
Java Magazin
Kolumne: Hitchhiker’s Guide to Docs as Code

Kolumne: Hitchhiker’s Guide to Docs as Code

Wir kennen das alle, diese gewisse Abscheu des Entwicklungsteams in puncto Dokumentation. Der Horror vor ungeeigneten Werkzeugen, fehlender Versionierung und binären Datenformaten. Wir schaffen Abhilfe. Schritt für Schritt führen wir Sie in dieser Kolumne an das Konzept Docs as Code heran, bei dem Sie Ihre technische Dokumentation - insbesondere Architekturdokumentation - genauso behandeln wie Ihren Code: schreiben, bauen, testen, committen, mergen. Gut, oder?

Ralf D. Müller, Gernot Starke


Traditionell nutzen Unternehmen primär Textverarbeitung als Grundlage technischer Dokumentation. Die entsprechenden Produkte – meistens Microsoft Word – sind überall vorhanden und das Management ist damit zufrieden. Entwicklungsteams sehen das ganz anders. Wir müssen mit Tools, die für Briefeschreiben und Single-User-Betrieb ausgelegt sind, komplexe, volatile und teilweise grafiklastige Dokumentationen erstellen und pflegen, über lange Zeit aktuell halten sowie Versionen und Releases unterstützen. Aua!Andere Ansätze, wie Javadoc, erfüllen nur einige spezielle Anforderungen an Dokumentation (Klassendokumentation) oder bieten nur einen eingeschränkten Funktionsumfang. Dann wäre da noch das bei Bloggern beliebte Markdown [1]. Das ist einfach und fast universell einsetzbar. Es scheitert aber bereits an längeren Tabellen oder größeren Dokumenten. Denn dafür wurde es auch nicht entwickelt. Wer dennoch Markdown bevorzugt, findet nützliche Tipps in einer älteren Ausgabe des Java Magazins [2]. AsciiDoc [3], [4] füllt diese Lücke. Dieses rein textuelle Format besticht einerseits durch eine einfache Syntax, die recht ähnlich zu Markdown ist. Es ermöglicht auf der anderen Seite aber vielseitige Formatierungen ähnlich wie WYSIWYG-Textverarbeitungen. Das Beste: Sie behandeln AsciiDoc genau wie Quellcode, aber dazu später mehr.Hello, WorldListing 1: „hello.adoc“:source-highlighter: coderay== Ein erstes Asciidoc(ument)Absätze könnenbeliebig viele Zeilenumbrüche enthalten. Erst nach einer Leerzeile beginnt ein neuer Absatz. === ÜberschriftenTextformatierungen, Aufzählungen (Listen) * kennen Sie von Wikis oder Markdown:* Formate wie *fett*, _kursiv_* Auch Links sind einfach: http://javamagazin.de[JavaMagazin]. .Code-Highlighting[source,groovy]10.times { println "Hello, AsciiDoc!" }:source-highlighter: coderay== Ein erstes Asciidoc(ument)Absätze könnenbeliebig viele Zeilenumbrüche enthalten. Erst nach einer Leerzeile beginnt ein neuer Absatz. === ÜberschriftenTextformatierungen, Aufzählungen (Listen) * kennen Sie von Wikis oder Markdown:* Formate wie *fett*, _kursiv_* Auch Links sind einfach: http://javamagazin.de[JavaMagazin]. .Code-Highlighting[source,groovy]10.times { println "Hello, AsciiDoc!" }Listing 2: „gradle.build“plugins { id "org.asciidoctor.convert" version "1.5.3" }plugins { id "org.asciidoctor.convert" version "1.5.3" }Wir verwenden übrigens Gradle aufgrund der unserer Meinung nach deutlich besseren Lesbarkeit, der angenehmen Kürze der Build-Files und der gr...

Java Magazin
Kolumne: Hitchhiker’s Guide to Docs as Code

Kolumne: Hitchhiker’s Guide to Docs as Code

Wir kennen das alle, diese gewisse Abscheu des Entwicklungsteams in puncto Dokumentation. Der Horror vor ungeeigneten Werkzeugen, fehlender Versionierung und binären Datenformaten. Wir schaffen Abhilfe. Schritt für Schritt führen wir Sie in dieser Kolumne an das Konzept Docs as Code heran, bei dem Sie Ihre technische Dokumentation - insbesondere Architekturdokumentation - genauso behandeln wie Ihren Code: schreiben, bauen, testen, committen, mergen. Gut, oder?

Ralf D. Müller, Gernot Starke


Traditionell nutzen Unternehmen primär Textverarbeitung als Grundlage technischer Dokumentation. Die entsprechenden Produkte – meistens Microsoft Word – sind überall vorhanden und das Management ist damit zufrieden. Entwicklungsteams sehen das ganz anders. Wir müssen mit Tools, die für Briefeschreiben und Single-User-Betrieb ausgelegt sind, komplexe, volatile und teilweise grafiklastige Dokumentationen erstellen und pflegen, über lange Zeit aktuell halten sowie Versionen und Releases unterstützen. Aua!Andere Ansätze, wie Javadoc, erfüllen nur einige spezielle Anforderungen an Dokumentation (Klassendokumentation) oder bieten nur einen eingeschränkten Funktionsumfang. Dann wäre da noch das bei Bloggern beliebte Markdown [1]. Das ist einfach und fast universell einsetzbar. Es scheitert aber bereits an längeren Tabellen oder größeren Dokumenten. Denn dafür wurde es auch nicht entwickelt. Wer dennoch Markdown bevorzugt, findet nützliche Tipps in einer älteren Ausgabe des Java Magazins [2]. AsciiDoc [3], [4] füllt diese Lücke. Dieses rein textuelle Format besticht einerseits durch eine einfache Syntax, die recht ähnlich zu Markdown ist. Es ermöglicht auf der anderen Seite aber vielseitige Formatierungen ähnlich wie WYSIWYG-Textverarbeitungen. Das Beste: Sie behandeln AsciiDoc genau wie Quellcode, aber dazu später mehr.Hello, WorldListing 1: „hello.adoc“:source-highlighter: coderay== Ein erstes Asciidoc(ument)Absätze könnenbeliebig viele Zeilenumbrüche enthalten. Erst nach einer Leerzeile beginnt ein neuer Absatz. === ÜberschriftenTextformatierungen, Aufzählungen (Listen) * kennen Sie von Wikis oder Markdown:* Formate wie *fett*, _kursiv_* Auch Links sind einfach: http://javamagazin.de[JavaMagazin]. .Code-Highlighting[source,groovy]10.times { println "Hello, AsciiDoc!" }:source-highlighter: coderay== Ein erstes Asciidoc(ument)Absätze könnenbeliebig viele Zeilenumbrüche enthalten. Erst nach einer Leerzeile beginnt ein neuer Absatz. === ÜberschriftenTextformatierungen, Aufzählungen (Listen) * kennen Sie von Wikis oder Markdown:* Formate wie *fett*, _kursiv_* Auch Links sind einfach: http://javamagazin.de[JavaMagazin]. .Code-Highlighting[source,groovy]10.times { println "Hello, AsciiDoc!" }Listing 2: „gradle.build“plugins { id "org.asciidoctor.convert" version "1.5.3" }plugins { id "org.asciidoctor.convert" version "1.5.3" }Wir verwenden übrigens Gradle aufgrund der unserer Meinung nach deutlich besseren Lesbarkeit, der angenehmen Kürze der Build-Files und der gr...

Neugierig geworden?


    
Loading...

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang