Dokumentation einfach gemacht

Dokumentation - es gibt nichts schlimmeres als nicht aktuelle und falsche Dokumentation. Da ist sogar keine Dokumentation besser. Keine Dokumentation ist spätestens dann keine Option, wenn mehrere Teilnehmer existieren und die Software für einen breiten/öffentlichen Nutzerkreis angedacht ist. Hier möchte ich mal aufzeigen, wie einfach Dokumentation sein kann. Spaß kann es sogar auch machen.

Überblick

IT/Software Dokumentation, da kann man viel Zeit investieren und ist mit dem Ergebnis oft nicht zufrieden. Da der Inhalt nicht vollständig oder nicht aktuell ist. Spätestens dann, wenn der Blick dann eher im Code geworfen wird, anstatt in der Dokumentation nachzugucken, hat die existierende Dokumentation versagt.

Warum ist das so? Hierzu gehört der nicht zu vernachlässigende Aufwand die Dokumentation aktuell zu halten. Je detaillierter eine Softwaredokumentation ist, desto höher ist der Aufwand um den Stand aktuell zu halten. Wird die Dokumentation dann noch nicht von den Entwickler und Architekten direkt erstellt, also diejenigen, welche die den direkten Kontakt zur Software und Code haben, so muss das Wissen und Inhalt an die Autoren transferiert werden. Wo Inhalt und Qualität verloren geht. Wird dann noch die Dokumentation mit komplexen Tools erstellt und in separaten SCM abgelegt ist das Dilemma vorprogrammiert.

Dokumentation soll als eine Disziplin des Software-Entwickler angesehen werden. So wie er seinen Code testen muss, so muss er auch seinen Code dokumentieren. Dazu gehört nicht nur sauberen Source Code, inkl. JavaDoc, sondern auch Softwaredokumentation die von Externen gelesen werden kann. Ohne direkt im Source Code zu schauen.

Ganz im Sinne der Minimierung von Medienbrüchen, wird hier ein Ansatz vorgestellt, um nah am Source Code entsprechende Softwaredokumentation zu erstellen. Hierfür wird AsciiDoctor (http://asciidoctor.org/) gesetzt und die Generierung der Dokumentation im Build-Prozess eingebunden.

AsciiDoctor

AsciiDoctor, basierend auf AsciiDoc, ist eine Toolchain die anhand vom erstellten Text verschiedene formatierte Ausgaben (HTML, DocBook, PDF etc) produzieren kann. Dabei bietet es verschiedene Formatierungsmöglichkeiten und Erweiterungen an. Ein paar der interessanten Erweiterungen sind: AsciiDoctorJ PDF und AsciiDoctorJ Diagram. Mit dem ersten kann PDF aus den AsciiDoc-Dateien erstellt werden. Aus dem zweiten, wie der Name andeutet, lassen sich Diagramme in Textform beschreiben, welche dann als Bild in integriert werden. So lässt sich z.B. mit Hilfe von PlantUML verschiedene UML-Diagramme erstellen und direkt in die Dokumentation integrieren.

Integration

Für die Integration von AsciiDoctor in den maven build gibt es das Projekt AsciiDoctorJ.

<plugin>
				<groupId>org.asciidoctor</groupId>
				<artifactId>asciidoctor-maven-plugin</artifactId>
				<version>1.5.5</version>
				<dependencies>
					<!-- AsciiDoctorJ enhancement to support PDF and Diagram output -->
					<dependency>
						<groupId>org.asciidoctor</groupId>
						<artifactId>asciidoctorj</artifactId>
						<version>${asciidoctorj.version}</version>
					</dependency>
					<dependency>
						<groupId>org.asciidoctor</groupId>
						<artifactId>asciidoctorj-pdf</artifactId>
						<version>${asciidoctorj.pdf.version}</version>
					</dependency>
					<dependency>
						<groupId>org.asciidoctor</groupId>
						<artifactId>asciidoctorj-diagram</artifactId>
						<version>${asciidoctorj.diagram.version}</version>
					</dependency>
				</dependencies>

   <!-- different  execution points -->

<!-- General configuration for all doctypes -->
				<configuration>
					<!-- Output doc in separate version directory -->
					<outputDirectory>${asciidoc.base.output.dir}</outputDirectory>
					<requires>
						<require>asciidoctor-diagram</require>
					</requires>
					<attributes>
						<project-version>${project.version}</project-version>
						<revnumber>${project.version}</revnumber>
						<revdate>${maven.build.timestamp}</revdate>
						<organization>${project.organization.name}</organization>
						<generated>${asciidoc.gen.dir}</generated>
					</attributes>
				</configuration>
</plugin>

Die allg. Konfiguration beinhaltet neben den Ausgabeordner auch Parameter, welche in der Dokumentation bei der Generierung verwendet werden können, z.B. Versionsnummer, Revision und Datum.

Pro Ausgabeformat muss nun ein execution-Point angegeben werden. Dabei werden die generierten Dateien jeweils in eigenen Unterordner platziert.

<executions>
					<!-- Different executions to generate different output formats -->
					<execution>
						<id>output-html</id>
						<phase>generate-resources</phase>
						<goals>
							<goal>process-asciidoc</goal>
						</goals>
						<configuration>
							<backend>html</backend>
							<outputDirectory>${asciidoc.base.output.dir}/html</outputDirectory>
						</configuration>
					</execution>
					<execution>
						<id>output-docbook</id>
						<phase>generate-resources</phase>
						<goals>
							<goal>process-asciidoc</goal>
						</goals>
						<configuration>
							<backend>docbook</backend>
							<doctype>book</doctype>
							<outputDirectory>${asciidoc.base.output.dir}/dockbook</outputDirectory>
						</configuration>
					</execution>
					<!-- -->
					<execution>
						<id>output-pdf</id>
						<phase>generate-resources</phase>
						<goals>
							<goal>process-asciidoc</goal>
						</goals>
						<configuration>
							<backend>pdf</backend>
							<outputDirectory>${asciidoc.base.output.dir}/pdf</outputDirectory>
							<attributes>
								<!-- expects images always under src/main/asciidoc <imagesdir>../../../target/generated-docs/${project.version}/images/</imagesdir> -->
								<imagesdir>${project.build.directory}/generated-docs/${project.version}/pdf/images/</imagesdir>
							</attributes>
						</configuration>
					</execution>
				</executions>

Ein

mvn generate-resources

generiert dann alle .adoc-Dateien, welche standardmäßig in src/main/asciidoc erwartet werden.

Eine vollständige Konfiguration ist in der pom.xml zu finden.

Verfassen

Nun steht die Infrastruktur, dass die Dokumentation automatisch generiert werden kann. Das Verfassen geht nach einer flachen Lernkurve bzgl. des Syntax schnell von der Hand.

= Blueprint
Hafid Haddouti
{project-version}
:numbered:
:toc: left
:toclevels: 3
:sectanchors:
:sectlinks:

include::01_summary.adoc[]
include::02_content.adoc[]
include::03_interfaces.adoc[]
include::20_monitoring.adoc[]
include::30_docker.adoc[]
include::10_docu.adoc[]
include::90_references.adoc[]

In dieser index.adoc werden weitere AsciiDoc-Dateien inkludiert. Zu sehen ist auch, dass ein Inhaltsverzeichnis am linken Sidebar erstellt werden soll. Ein Parameter {project-version} aus der Maven-Konfiguration ist auch integriert.

Die weiteren Dateien können im GitHub-Projekt genauer angeschaut werden.

Wie oben schon angedeutet, lassen sich auch UML in die Dokumentation integrieren. Dabei lässt sich z.B. PlantUML verwenden.

=== Components

[plantuml, diagram-arch-components-general, png]
....
@startuml
!pragma graphviz_dot jdot
skinparam componentStyle uml2
interface "Metrics" as IMetrics
interface "Actuator" as IActuator
interface "REST" as IRest

[ES] <<Storage>>
[JPA] <<Storage>>

IMetrics - [Blueprint App]
IActuator - [Blueprint App]
IRest - [Blueprint App]

IMetrics - [Monitoring]

[Blueprint App] --> [ES]
[Blueprint App] --> [JPA]
@enduml
....

Produziert folgendes Bild in die generierte Dokumentation:

Neben PlantUML unterstützt AsciiDoctor Diagram noch weitere Diagrammbeschreibungen wie z.B. Ditaa, Graphviz usw.

Bzgl. PlantUML sei erwähnt, dass PlantUML standardmäßig Graphviz und Dot für die Diagrammerstellung verwendet. Speziell Dot muss auf dem Betriebssystem vorinstalliert werden und wird nicht im Maven-Plugin mit ausgeliefert. Dies kann jedoch mit folgender Anweisung in der Diagrammbeschreibung umgangen werden:

!pragma graphviz_dot jdot

In dem Fall wird die PlantUML-Implementierung von Dot verwendet. In dieser Varianten werden nicht alle Funktionen sauber unterstützt, z.B. Pfeile und die Anordnung der Elemente ist nicht immer "optimal".

Eine alternative Diagrammbeschreibung mit Ditaa sieht wie folgt aus:

[ditaa]
....
	+---------+       +----------+
	|  REST   |       |  Monitor |
	+---------+       +----------+
	      |                 |
	      v                 v
	+----------------------------+
	|       Infrastructure       |
	+----------------------------+
	|    JPA      |      ES      |
	+----------------------------+
	              |
	              v	
	+----------------------------+
	|            Core            |
	+----------------------------+
	| Domain Model | Services    |
	+----------------------------+
	
....

Als Bild sieht das dann wie folgt aus:

Fazit

Hier wurde aufgezeigt, wie mit Hilfe von AsciiDoctor und Erweiterungen die Grundlage geschaffen werden kann, um einfach und aktuelle Dokumentation zu erstellen. Dabei wurde auch betrachtet, wie UML-Diagramme integriert werden können.

Speziell die Erstellung von UML-Diagrammen wird schnell unübersichtlich und ist keineswegs mit den umfangreichen und professionellen UML Tools zu vergleichen. Dies ist hier jedoch auch nicht der Fokus. Wenn schon solche simple Dokumentationswerkzeuge keine Anwendung finden, dann nutzt auch das so tolle UML Werkzeug nichts.

Ein aktuelle Dokumentation ist auf der GitHub Page von Blueprint zu finden. Dies wird bei jedem Build automatisch generiert und bereitgestellt. Fehlt nur noch die Befüllung mit Inhalt - das passiert noch nicht automatisch ;-).