Continuous Documentation

Ich persönlich nutze seit Jahren Markdown zum Schreiben meiner Texte. Auch diesen Beitrag habe ich mit Markdown erstellt, weil die Syntax so einfach ist und es für so ziemlich jede Plattform Plugins oder Editoren gibt, die Markdown unterstützen. Auf Fachkonferenzen zur Programmierung sehe ich aber aktuelle immer wieder Asciidoc als Standard für die automatisch generierte Dokumentation von Software. In diesem Artikel bei JAXEnter wird Asciidoc in Kombination mit Gradle und Eclipse als Tool zur Continuous Documentation vorgestellt: Technische Dokumentation mit AsciiDoc, Gradle und Eclipse.

Dabei erzeugt das Build-Tool im Rahmen des Build-Prozesses automatisch eine menschenlesbare Dokumentation, z.B. in Form von HTML oder als PDF-Datei. Die Syntax von Asciidoc unterscheidet sich ein wenig von Markdown und wurde auch um zusätzliche Funktionen erweitert. Was für uns Entwickler am interessantesten sein dürfte, ist die Möglichkeit, UML-Diagramme in Textform zu definieren, die dann als hübsche Grafiken ausgegeben werden.

Ich selbst habe noch nicht mit Asciidoc gearbeitet, aber es rückt auf meiner To-Try-Liste immer weiter nach oben. 😉


Mit welchen Tools dokumentierst du deine Software? Ist die Dokumentation bei euch schon in den Build-Prozess integriert?

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

To create code blocks or other preformatted text, indent by four spaces:

    This will be displayed in a monospaced font. The first four 
    spaces will be stripped off, but all other whitespace
    will be preserved.
    
    Markdown is turned off in code blocks:
     [This is not a link](http://example.com)

To create not a block, but an inline code span, use backticks:

Here is some inline `code`.

For more help see http://daringfireball.net/projects/markdown/syntax