AsciiDoc oder Markdown

Die Entscheidung für oder zuweilen auch gegen eine Technologie in der Software-Entwicklung ist selten klar. Der Rückblick auf vergangene Entscheidungen ist dann doch von der Hoffnung getragen, für kommende Entscheidungen etwas zu lernen. Oft genug heißt das, es beim nächsten Mal besser zu machen. Denn die Technologie bleibt uns oft viel länger erhalten, als ursprünglich gedacht, die Wartung von Altem ist ein beachtlicher Teil unserer Arbeit.

Wir haben uns, zum Beispiel, vor knapp zehn Jahren für Joomla als CMS für unsere Hauptwebseite entschieden und gegen Wordpress. Meiner Erinnerung nach war das damals keine falsche Entscheidung, aber schon drei, vier Jahre später und zumal heute dominiert Wordpress und Joomla ist faktisch nicht mehr existent. Aber unsere Webseite läuft, unglaublich, immer noch auf Joomla.

Eine andere Entscheidung war, AsciiDoc und nicht Markdown als Basis für unsere interne wie auch öffentliche Dokumentation zu nehmen. Ich bin mir nicht mehr sicher, ob das eine ganz explizite Entscheidung war. Wir hatten unser erstes großes Web-App-Projekt mit Java und Spring Boot aufgezogen und dort gab es diesen API-Doku-Generator Spring Rest Docs, der AsciiDoc benutzte. Das muss so um 2017 gewesen sein. Markdown war schon damals die dominierende einfache Textauszeichnungssprache, aber AsciiDoc – vor allem mit Asciidoctor als Prozessor – erschien mir als die deutlich ausgereiftere Lösung. Das stimmt auch heute noch. AsciiDoc hat deutlich mehr Funktionen und bietet sich für große technische Dokumentation an, während Markdown nie für auch nur mittelkomplexe Dokumente gedacht war, ja ursprünglich nicht mal eine richtige Spezifikation hatte. Interessanter Weise hat auch AsciiDoc bis zum heutigen Tage keine Spezifikation, aber es gab die eine kanonische Implementierung – Asciidoctor – mit guter, detaillierter Doku, während es für Markdown einen ganzen Zoo an Dialekten gibt; und ironischer Weise seit knapp zehn Jahren die Spezifikation eines kleinsten, gemeinsamen Nenners, CommonMark.

Im Jahr 2017 hielt ich AsciiDoc für die bessere Lösung für unsere Anforderungen, heute, sechs Jahre später, habe ich meine Meinung geändert. Ich gebe Markdown den Vorzug und das hat im Wesentlichen zwei Gründe: Popularität und Einfachheit.

Popularität allein bedeutet natürlich nicht, dass eine bestimmte Technologie an sich besser ist, bringt aber oft Vorteile mit sich, die selbst faktische Defizite kompensieren können. So ist Markdown per se keine Sprache für große technische Dokumentation, es gibt aber viele großartige Lösungen für technische Dokumentation, die auf Markdown aufsetzen, darunter unter anderem Docusaurus, VitePress und in gewisser Weise auch Astro. Der ganz überwiegende Teil an Dokumentation, die man als Software-Entwickler liest, ist in Markdown geschrieben (Binse).

Das Ökosystem um Markdown herum ist riesig, es gibt verschiedene Implementierungen, in allen erdenklichen Sprachen. AsciiDoc gibt es eigentlich nur in Ruby, das man noch nach Javascript oder Java querkompiliert servieren kann. Es gibt kein Plugin, keine Diagramm- oder Mathe-Erweiterung, die es nicht irgendwo für Markdown gibt. Die Unterstützung in Editoren und IDEs, das Tooling allgemein, ist recht spektakulär. Es gibt verschiedenste einfache Editoren, die das Schreiben von Texten angenehm machen wollen. Es war die überarbeite Markdown-Unterstützung in VS Code, die mit Code-Vervollständigung, automatischen Links, einfachem Refactoring, Folding und auch dem Funktionieren in VS Code Web aufwartet, die mich vor ein paar Monaten dazu brachten, die Entscheidung für AsciiDoc zu überdenken. Die Unterstützung für AsciiDoc in VS Code ist nicht schlecht, aber sie ist der von Markdown nicht ebenbürtig. Und die aufgezählten Funktionen jede für sich sind natürlich keine Revolution, aber in der Summe ergibt sich durchaus ein anderes Arbeiten.

Innovationen wie das Einbetten von Komponenten in den Text (MDX), die auf AsciiDoc oder Markdown als „Plattform“ aufsetzen, also nicht Innovationen in der Kerntechnologie an sich, gibt es eher bei Markdown und ich denke auch das hängt mit der weiten Verbreitung zusammen. Popularität bedeutet zuletzt, dass ich, wenn ich etwas Neues baue – nehmen wir zum Beispiel eine Astro-Seite – von Markdown-Unterstützung ausgehen kann. Ich kann auch davon ausgehen, dass es AsciiDoc-Unterstützung nicht gibt.

Die etwas überraschendere Erkenntnis für mich war, dass die Einfachheit von Markdown ein Vorteil ist. Als Entwickler tendiert man dazu, komplexe Lösungen gut zu finden. Gleichsam haben wir über die vergangenen Jahre ein um das andere Mal gelernt, dass man Softwarelösungen so einfach, ja primitiv wie irgend nur möglich bauen sollte. Und ein um das andere Mal sind wir gescheitert und haben es wieder zu schön, zu komplex gemacht.

Obwohl ich jahrelang leidlich regelmäßig AsciiDoc geschrieben habe, musste ich eigentlich immer gewisse Syntaxelemente nachschlagen – oft genug sogar ein Codelisting: Sind es drei Bindestriche, vier, oder waren es Unterstriche? Definitiv schlage ich aber beim Schreiben von Tabellen nach. Obwohl ich Markdown jahrelang weniger geschrieben habe, muss ich weniger oft die Dokumentation zu Rate ziehe. Gerade Tabellen sind ein interessantes Beispiel. In Markdown (wir nehmen hier mal GitHub Flavoured Markdown) sind Tabellen relativ eingeschränkt, in AsciiDoc ist mehr oder weniger alles möglich. Allerdings ist es für mich als jemand, der schon mal ein bisschen Webentwicklung gemacht hat, viel einfacher, die Tabelle in HTML zu schreiben und in Markdown einzubetten, als die komplizierte AsciiDoc-Syntax nachzuschlagen und korrekt niederzuschreiben. MDX bietet mit der Einbettung von Komponenten einen anderen potentiellen Ansatz für komplexe Tabellen oder andere ausgefallenere Inhaltselemente. Und einfache Tabellen gehen mir in Markdown ohne Nachschlagen von der Hand.

Wie ich die Entscheidung AsciiDoc oder Markdown bedachte, fragte ich mich an einem Punkt, welche Sprache meine Nicht-Entwickler-Kollegen eher erlernen sollten. Und die Antwort darauf ist so klar und einfach, dass man verblüfft die letzten Paragraphen wegwischen, aussparen kann. Und sie bindet die Popularität und Einfachheit zusammen, denn es müsste natürlich Markdown sein.