HOCHWERTIGE ENTWICKLUNGSDOKUMENTATION AUTOMATISCH MIT ASCIIDOC
←
→
Transkription von Seiteninhalten
Wenn Ihr Browser die Seite nicht korrekt rendert, bitte, lesen Sie den Inhalt der Seite unten
HOCHWERTIGE
ENTWICKLUNGSDOKUMENTATION
AUTOMATISCH MIT ASCIIDOC
| von MARTIN SERNOW
Je größer ein Softwareprojekt, desto befindet und die „goldenen Henkel“ ganz und die Dokumentation dort abzulegen,
höher die Wahrscheinlichkeit, dass das sicher später nachgeholt werden – so je- wo sich die dokumentierte Problematik
Anpassen der Entwickler-, System- und denfalls der gute Vorsatz. befindet. Hier kann die Auszeichnungs-
Releasedokumentation von den Bear- sprache AsciiDoc Abhilfe schaffen. Wir
beitern vergessen wird. Sei es, weil zu Die Lösung für dieses Problem wäre, den verwenden es, um den Releaseletter, die
viel Dokumentation existiert oder weil Medienwechsel zwischen Intellij+Git und Installationsanleitung, das Systemhand-
sich das Projekt in einer kritischen Phase Word+SVN möglichst gering zu halten buch und den Systementwurf durch Ascii-
Doc automatisiert generieren zu können.
Durch die Umstellung von einem Worddo-
kument auf mehrere AsciiDoc-Dokumen-
te ergeben sich verschiedene Vorteile, die
WAS IST ASCIIDOC?
nachfolgend erläutert werden.
AsciiDoc ist eine Auszeichnungssprache, mit der man schnell und einfach formatierte Dokumente
erstellen kann. AsciiDoc kann mithilfe des Tools AsciiDoctor1 direkt in den Softwareerstellungs-
WELCHE PROBLEME BEI DER SYSTEM-
und Build-Prozess integriert werden. Aus der Code-Dokumention werden Lieferartefakte erzeugt,
UND RELEASEDOKUMENTATION
die mit spezifischen Formatvorlagen für unterschiedlichste Ausgabeformate hinterlegt werden
WERDEN DURCH ASCIIDOC GELÖST?
können. Dadurch entfällt die neben oder nach der Entwicklungs- und Releasephase anfallende
zusätzliche Dokumentationsphase. Die erzeugte Dokumentation kann durch viele Werkzeuge
Softwareentwickler nutzen für ihre Ar-
(zum Beispiel Intellj, Eclipse, Visual Studio) geöffnet, erweitert und angesehen werden, ohne dass
beit eine Entwicklungsumgebung (zum
weitere Anwendungen gestartet werden müssen.
Beispiel IntelliJ) sowie gegebenenfalls
weitere Entwicklungswerkzeuge, wie
52 | .public 01-21 | Informationstechnologie
rieren. In vielen Fällen schreibt AsciiDoc
sogar selbst vor, wie bestimmte Informa-
Eine Auszeichnungssprache ist eine maschinenlesbare Sprache für die Gliederung und Forma-
tionen formatiert sein müssen (zum Bei-
tierung von Texten. So kann man mit einfachen Mitteln wie *Fett* schreiben, mit TIP: ein Icon
spiel für Überschriften, Code Snippets,
einfügen und per image:icons/avatar.png[title="Avatar"] sogar ein Bild ins Dokument einfügen.
Bilder oder Tabellen).
Ziel ist es, mit wenig Aufwand ein einheitliches und gut formatiertes Dokument zu schreiben.2
Grafiken sind bei der System- und Ent-
wicklerdokumentation oft ein wich-
tiges Mittel, um die Technik dahinter
verständlich zu machen. Man möchte
zum Beispiel Konsole, Datenbankviewer Andere Entwickler, die sich genau mit die Medien so ablegen, dass sie im ge-
und Browser und verwalten ihre Arbeit diesem Code befassen, können prob- nerierten Dokument richtig angezeigt
in einer modernen Versionsverwaltung lemlos das entsprechende AsciiDoc-Do- werden. Bei MS Word werden die Medi-
(zum Beispiel Git). Die Dokumentation kument aufrufen, das entsprechende In- en einfach per Drag & Drop in das Do-
dagegen findet über MS Word und die formationen für die Arbeit an der Klasse kument „gezogen“. Allerdings ist danach
Verwaltung über eine „klassische“ Ver- bereitstellt. Zudem können Änderungen das Aktualisieren der Bilder schwierig.
sionsverwaltung statt (zum Beispiel aufgrund von Change Requests oder Dafür bietet Word nur an, die Medien
svn). Der an dieser Stelle entstehende Bugs sofort und an Ort und Stelle vorge- über eine Referenz zu ihrem Ablage-
Medienbruch und zusätzliche Aufwand nommen werden. ort zu speichern. AsciiDoc ermöglicht
führen häufig dazu, dass die Anpassung das analog über die Referenzierung via
oder Aktualisierung der Dokumentation Code und Dokumentation können in ei- URL-Notation des Ablagepfads. Dabei
verschoben oder sogar ganz vergessen nem gemeinsamen Review-Prozess der reicht auch eine relative Referenz mit
wird. Auch die Suche nach Informatio- Entwicklung geprüft werden. Den Revie- Bezug zu einem zentralen Webserver
nen in der Dokumentation erweist sich wern stehen beide Prüfobjekte gemein- aus, so dass man die Medien zentral
oft als schwierig, da viele Entwicklungs- sam zur Verfügung, und sie erkennen am bearbeiten, zum Download anbieten
umgebungen nicht sehr leistungsfähig in Fehlen des AsciiDoc-Dokuments, dass und Duplikate vermeiden kann.
der separat abgelegten Dokumentation eine Dokumentation noch aussteht.
suchen können. Das Ausgabeformat von AsciiDoctor
Ein weiteres Problem ist das einheitliche ist standardmäßig auf PDF und HTML5
Layout von MS-Word-Dokumenten. Da beschränkt. Das Tool Pandoc3, das oft
es sehr viele Möglichkeiten und Optio- für Medienkonvertierungen über die
nen gibt, ein Dokument „wunschgemäß“ Kommandozeile verwendet wird, bietet
zu formatieren, steigt die Vielfalt der weitere Ausgabeformate an. Zusätzlich
„Layouts“ und Formatierungen, je län- kann man Dokumente in mehreren For-
ger ein Dokument bearbeitet wird und je maten exportieren: So kann man für Pro-
mehr Personen daran arbeiten. Die Ent- jektmitarbeiter die Dokumentation auf
wickler verlieren sich immer mehr darin, einem Siteserver hosten, den Beteiligten
Design über Inhalte zu stellen. ein PDF schicken und gegebenenfalls für
die nachträgliche Bearbeitung noch ein
Abbildung 1: Projektstruktur mit integrierter ADOC-Datei AsciiDoc bietet zwar ebenfalls eine gute Docx bereitstellen. Um jedoch Kommen-
Auswahl an Dokumentdesign- und For- tare von Nutzern zurück ins System zu
matierungsmöglichkeiten, allerdings spielen und dort weiterzuverarbeiten,
wird das Design erst bei der Erzeugung wäre ein noch zu erstellendes Tool not-
des Artefakts (wie PDF, HTML, DOCX, wendig, das diese Kommentare aus dem
Dagegen liegen bei der Verwendung von PPT) auf Basis von Formatvorlagen (Tem- dem Dokument extrahiert und zum Bei-
AsciiDoc die Dateien für die Dokumen- plates) von AsciiDoctor über den Inhalt spiel als To-dos an das entsprechende
tation direkt beim Code, im selben Ver- „gestülpt“. So müssen und können sich AsciiDoc-Dokument anhängt.
zeichnis wie die implementierte Klasse. Entwickler vor allem den Inhalt konzent-
Informationstechnologie | .public 01-21 | 53WIE INTEGRIERT MAN DEN BUILD-
PROZESS IN SEIN PROJEKT?
Ein einfaches Beispiel zeigt, wie man eine
Datei in einem Build Tool wie Maven inte-
grieren kann, damit beim Build-Process
das entsprechende Dokument mitgene-
riert und an die Beteiligten ausgeliefert
werden kann:
• Im ersten Schritt bindet man das
asciidoctor-maven-Plugin ein, am bes-
ten im Build Process mit dem Profil
asciidoc, damit man über dieses Pro-
fil steuern kann, wann man die Doku-
mente generiert.
• A ls Nächstes legt man die verschiede-
nen Konvertierungen (executions) fest–
in diesem Fall für den Systementwurf
Abbildung 2: Projekt Object Model um ADOC Plugin erweitert
export
Jira Jira Issues Open Issues generate
PDF
arc PDF
asciidoc
export
Chance Log template asciidoctor
Chance Log Confluence
publish to
Git- diagram PDF Confluence
Repository is derived from
plugin plugin
Pages
Contributors generate HTML5
export HTML
Contributors
include your solution read htmlSanityCheck
architecture plant reveal.js
Element documentation UML template generate HTML Error
export DocBook
EA Notes DOCBook Report
Sparx EA
Model
read
Diagram fix prepend
PNGs Encoding filename convert
Visio Project to Docx
export pandoc DOCX
Visio
generate
Speaker- Deck convert
Notes to EPub
PPT- Reveal.js
Deck EPub
Presentation export
PPT Slide as
JPG
LEGEND
export Worksheets your documentation build task under version control
xlsx-Sheet Exel as csv and adoc
output document software component gradle task
export Intermediate document proposed direction of control
Markdown Markdown Asciidoc
Abbildung 3: Übersicht der Möglichkeiten von DocToolchain6
54 | .public 01-21 | InformationstechnologieDocBook (dies kann später zu dem Das Werkzeug DocToolchain4 ermöglicht ZUSAMMENFASSUNG
Word-Dokumententyp docx konver- es, dynamisch noch mehr entwicklungs-
tiert werden). In der Konfiguration relevante Informationen automatisiert Mit dem Wechsel von MS Word auf eine
sagt man mit dem Tag „backend“, in die AsciiDoc-Dokumente einzufügen. Dokumentation direkt am Code durch
dass man ein docbook wünscht. Für Ursprung der mittlerweile zahlreichen, AsciiDoc werden den Entwicklern ma-
das DocBook-Dokument kann man automatisch Dokumentationsfunktio- nuelle Arbeiten abgenommen. Dies min-
html oder auch pdf verwenden, na- nen unterstützenden DocToolchain war dert das Fehlerpotenzial und versetzt
türlich immer mit dem entsprechen- der Wunsch, Diagramme aus dem Enter- Entwickler in die Lage, Code schneller zu
dem Doctype. prise Architekt5 in AsciiDoc-Dokumente verstehen und, neben JavaDoc7, besser
• B eliebig weitere executions kann einzubinden (siehe Abbildung 3). zu dokumentieren. Der Release-Prozess
man erzeugen, um entweder den wird durch die automatische Zusam-
Systementwurf in weitere Formate Beispielszenario menstellung von Release-Dokumentati-
zu konvertieren oder auch andere Ein gutes Beispiel für „Documentation onen schlanker, die manuelle Arbeit ent-
Dokumente zu erzeugen. am Code“ aus der Projektpraxis ist der fällt zum großen Teil. Alles in allem „lebt“
• In der Konfiguration werden allge- Einsatz von AsciiDoc im Ticketprozess. die Entwicklungsdokumentation und
meine, für alle executions gültige
Werte übergeben, wie beispielsweise
Änderungen im Programmcode auf-
grund eines Tickets werden über ein
wird stetig aktualisiert und publiziert. •
das Ausgabeverzeichnis (hier out- spezielles Commit in Git abgebildet. Ab-
putDirectory), welche Logeinträge schließende Commits wurden um das
geschrieben werden und woher die Kennzeichen „#releaseletter“ erweitert.
Quelldateien kommen. DocToolchain sammelt automatisch
für den Releaseletter alle Commits aus
DOCTOOLCHAIN der Git-Historie und schreibt sie in den
Releaseletter. Somit werden wichtige-
Doch was, wenn man mit mehreren Tools Feature-Entwicklungen oder Fehlerkor-
wie Sparx EA, Git, Jira oder Visio arbeitet rekturen im Releaseletter verzeichnet,
und daraus die Inhalte in seinem Ascii- ohne dass ein Release-Verantwortlicher
Doc -Dokument anzeigen und aktuell die entsprechenden Tickets suchen und
halten möchte? manuell hinzufügen muss.
1 https://asciidoctor.org/ (abgerufen am 26.10.2020).
2 Eine genaue Auflistung der AsciiDoc Formatierungen siehe hier: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ (abgerufen am 30.03.2021).
3 https://pandoc.org/ (abgerufen am 30.03.2021).
4 https://doctoolchain.github.io/docToolchain/ (abgerufen am 26.10.2020).
5 https://www.sparxsystems.de/ (abgerufen am 26.10.2020).
6 https://doctoolchain.github.io/docToolchain/#_overview_of_available_tasks (abgerufen am 26.10.2020).
7 https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html (abgerufen am 26.10.2020).
Informationstechnologie | .public 01-21 | 55Sie können auch lesen
