Dokumentation technisch umsetzen

“Lucas:” Hallo und herzlich willkommen zu einer neuen Folge des INNOQ Podcasts. Heute wollen wir darüber sprechen, wie man eine Dokumentation technisch am besten umsetzt. Und dafür habe ich mir den Lars eingeladen. Hallo, Lars.

“Lars:” Hallo, Lucas.

“Lucas:” Bevor wir loslegen, sag doch mal ein paar Worte zu dir.

“Lars:” Ich bin Senior Consultant bei INNOQ, bin seit dreieinhalb Jahren dabei und als ich zur INNOQ gestoßen bin, habe ich am Anfang Frontend Entwicklung gemacht und bin jetzt dann eher in Richtung Backend gegangen. Und momentan im Projekt habe ich sehr viele verschiedene Rollen. Unter anderem kümmere ich mich dort auch um die Dokumentation der Software.

“Lucas:” sehr gut. Wir haben auch darüber schon mal gesprochen gehabt. Wir sind zufällig im selben Projekt, deswegen habe ich das schon live miterlebt, was Lars gebaut hat, dass diese Dokumentation schon ein paar besondere Anforderungen hat, die man nicht überall hat, aber dass vielleicht Teile davon Sachen sind, die man in anderen Projekten auch begegnet. Dass wir da vielleicht ein bisschen darüber diskutieren können, wie das gelöst wurde, damit man das vielleicht ins eigene Projekt mitnehmen kann, oder als Inspiration, oder vielleicht auch als Anti-Patterns, wie auch immer ihr das mitnehmen wollt, diskutieren können. Heute wollen wir uns ganz klar darauf konzentrieren, wie man denn das technisch umsetzt. Wir nehmen mal als gegeben voraus, dass wir Dokumentationen schreiben wollen. Das ist etwas, worüber wir uns einig sind.

“Lars:” Ja, bin ich auch der Auffassung, dass Dokumentation gut ist.

“Lucas:” Es gibt eben ganz viele verschiedene Arten von Dokumentation. Es gibt verschiedene Templates, denen man folgen kann bei so einer Dokumentation. Dann gibt es sowas wie arc42, das wir zum Beispiel in diesem Projekt verwenden. Da können wir vielleicht auch mal eine Folge zu machen. Aber da würde ich mal den Gernot fragen, ob er Lust hat, mal mit mir darüber zu sprechen, was es da so gibt und warum man das vielleicht machen möchte. Aber heute geht es tatsächlich nicht darum, was genau wir dokumentieren oder in welcher Struktur wir das dokumentieren, sondern wie wir dafür sorgen, dass es sichtbar ist für die Leute, dass die Leute editieren können und so weiter. Das ist heute unser Fokus.

“Lars:” Von einem unserer Principals, dem Phillip Ghadir, gibt es so ein schönes Zitat, der sagt: „Und wenn es schon Word auf SharePoint ist, die Doku, Hauptsache es gibt Doku.“ Er stellt sich auf den Standpunkt, dass selbst eine Word Doku besser ist als gar keine Doku. Und ich glaube, im Projekt wäre aber eine Word Doku nicht gut gekommen und wir wollen vielleicht mal darauf hinkommen, jetzt heute in den Podcast, was wird denn statt Word gemacht haben.

“Lucas:” Exakt. Genau. Was nicht heißen soll, dass wenn ihr jetzt eine Word Doku habt und damit zufrieden seid, dass ihr das ändern müsst. Das ist absolut in Ordnung, aber es kommt eben sehr auf die Anforderungen an und über die wollen wir heute auch ganz ausführlich am Anfang erst einmal sprechen. Bevor wir das tun, kannst du mal kurz einordnen, über welche Arten von Dokumentation wir an dieser Stelle reden? Da gibt es unzählige.

“Lars:” Ja, genau. In dem Projekt, in dem wir arbeiten, gibt es jetzt einen sogenannten Documentation Hub oder so ähnlich habe ich das zumindest mal getauft und der ist schon eher technisch orientiert. Das heißt, da haben wir so was wie Code Doku drin, da haben wir API Doku drin, da haben wir so was wie HTTP Restschnittstellen. Da haben wir aber auch so was wie Java basierte und Swift basierte SDK mit drin. Da haben wir auch Architektur Dokumentation drin, aber jetzt eher weniger irgendwelche User Manuals. Das ist jetzt eher nicht so, dass man dann sagt: Installieren Sie sich jetzt Produkt XYZ, dann klicken Sie hier drauf und klicken Sie darauf. Sondern das ist eher gedacht als Zielgruppe von Entwickler:innen und Systemintegration:innen. Das heißt, gegebenenfalls wollt ihr das auch nicht implementieren, sondern einfach nur mal schauen: Was macht das Produkt? Wie kann ich das mit meinem Produkt? Wie kann ich das in meine Landschaft integrieren? Aber dann eben für die Leute, die dann tatsächlich die Integrationsarbeit durchsetzen oder umsetzen. Aber wie gesagt, nicht für End User. Dafür ist es nicht gedacht.

“Lucas:” Ich glaube, das sollte man vielleicht nochmal kurz einschieben, um was für eine Art von Projekt es sich handelt. Es handelt sich um ein Projekt, bei dem ein Softwareprodukt gebaut wird, was integriert werden muss in andere Systeme. Das heißt, die Entwicklerinnen wollen dieses Tool oder diese Sachen in ihr existierendes Produkt integrieren. Das heißt also, das ist die Hauptgruppe von Leuten, die das konsumiert. Aber genauso ist es natürlich wichtig, dass Leute, die neu ins Projekt kommen, sich auch direkt orientieren können, dass sie vielleicht sogar ein paar Informationen mehr sehen als diese externen Leute, die auf diese Dokumentation zugreifen, weil sie vielleicht auch auf Interna zugreifen dürfen. Aber das ist eine ganz klare Dev-Dokumentation und nicht Public Facing für Leute, die außerhalb des Entwicklungsbereichs unterwegs sind. Zumindest nicht primär. Um sich da jetzt irgendwie so eine Übersicht zu verschaffen. Was kann das Produkt im Allgemeinen? Das kann man sicherlich auch mit dieser Dokumentation machen, aber es ist schon ein ganz klarer Fokus auf Entwicklungsabteilungen gegeben.

“Lars:” Mit den verschiedenen Zielgruppen sind wir eigentlich schon mittendrin in der Anforderungsdiskussion. Wir haben nämlich zum Beispiel als eigene Sache in dem Projekt so was wie Exportkontrolle. Manchmal müssen irgendwelche Dinge verschickt werden ins Ausland, irgendwelche Hardware und dann mussten wir das dokumentieren, was in dieser Hardware drin ist. Ist jetzt zum Beispiel ein Akku drin, dann ist das irgendwie blöd zum Verschicken. Oder ist da irgendwelche Krypto drin, die man nicht exportieren darf? Oder lauter solche Späße. Und da gibt es eben auch einen bestimmten Teil in der Dokumentation, das ist dann Exportkontrolle und da sind dann irgendwelche ganz tollen Excel Sheets drin, wo man dann genau nachweisen muss, was man alles getan hat. Und logischerweise ist das natürlich nur relevant für die drei Leute, die sich undankenswerterweise darum kümmern müssen. Aber natürlich nicht für die Leute, bei denen das dann ankommt am Ende des Tages. Die, die die Hardware entgegennehmen, die interessiert das einfach nicht. Die wollen nur, dass sie die Hardware haben. Aber intern ist es schon wichtig, dass das alles irgendwie einen Papertrail hat, was man da gemacht hat, wenn man die Hardware in einen Karton gepackt hat.

“Lucas:” Genau. Und genauso ist zurzeit eben verschiedenes Publikum, die Leute, die bei unseren Kunden arbeiten und die Leute, die bei den Kunden unseres Kunden arbeiten. Vielleicht gibt es internen APIs, die von außen nicht erreichbar sind, aber die natürlich für die internen Entwickler und Entwicklerinnen totale Relevanz haben. Oder vielleicht gibt es zu einem Bereich zwar eine Public API, das ist die API-Beschreibung, aber die genaue Architektur von dieser Komponente, die soll jetzt nicht unbedingt den Kunden und Kundinnen zur Verfügung gestellt werden. Das sind so diese Arten von verschiedenen Dokumentationen, über die wir hier sprechen. Das ist etwas, was ich jetzt bisher noch in keinem Projekt gebraucht habe. Das war das erste Mal, dass ich so eine Anforderung hatte. Aber hier ist das wirklich essenziell wichtig, dass man sagen kann: Bitte zeichne jetzt diesen Bereich aus als Public facing, die sind für intern, die sind für Exportkontrolle. Solche verschiedenen Gruppen. Und wir wollen natürlich dabei trotzdem die Duplikation vermeiden. Dass die Dokumentation doppelt geschrieben wird, weil es sowieso immer schon eine Herausforderung ist, eine Dokumentationen up to date zu halten und dann jetzt auch noch zu sagen: Bitte pflegt das einmal in diese Dokumentation ein, einmal in diese und einmal in diese. Da kann man sich vorstellen, dass das vielleicht sogar noch mehr ins Auge geht, als es sowieso schon oft tut.

“Lars:” Manche von unseren Hörerinnen haben jetzt vielleicht ein Begriff Multi-Mandantenfähigkeit im Kopf und damit wären sie gar nicht mal so falsch. Es ist schon eine bestimmte Form von Multi-Mandantenfähigkeit. So was wie Versionierung hat man auch bei vielen Projekten, dass man irgendwie Doku Version 1.0 und Version 1.1 hat. Das hat man auch bei Open-Source-Projekten ganz oft. Und jetzt haben wir noch so als Zusatzanforderung, dass es eben nicht nur verschiedene Versionen geben muss, sondern eben auch verschiedene Zielgruppen, die dann auch bestimmte Sachen sehen dürfen.

“Lucas:” Apropos Zielgruppen ist es natürlich auch so, dass nicht unbedingt jede Person auf diese Dokumentation zugreifen soll. Wir brauchen irgendeine Art von Zugriffskontrolle. Da könnte zum Beispiel sein, dass man das einfach hält. Es gibt einen geteilten Usernamen, Passwort für alle oder man möchte es vielleicht integrieren mit irgendeinem Single Sign-On System beispielsweise. In dem Fall wollen wir das integrieren bei allen oder bei fast allen Versionen dieser Dokumentation. Das ist die zweite Anforderung, die wir in dem Projekt hatten. Eine weitere Besonderheit ist, dass es ein Produkt ist, was eben aus verschiedenen Teilen besteht. Sowohl aus Web Komponenten, aus API Komponenten, als auch aus mobile Apps, die auch irgendeine Art von SDK zur Verfügung gestellt bekommen müssen. Daraus ist diese Anforderung entstanden, dass man aus verschiedenen Quellen diese Dokumentation zusammenstellen soll. Beispielsweise haben iOS Leute ihre Dokumentation in dieser iOS-Dokumentationswelt geschrieben, also als Source Kommentare und wollen das jetzt irgendwie exportieren, damit man das eben verwenden kann oder darauf zugreifen kann, wenn man jetzt eben als Kunde sagt: Ich möchte jetzt gerne dieses SDK in mein System integrieren. Ich bin jetzt iOS Entwicklerin und ich möchte jetzt gerne die iOS SDK in meiner App benutzen. Das wäre jetzt so die andere Anforderung.

“Lars:” Das mit den verschiedenen Quellen ist natürlich auch wiederum eine kleine Problematik, weil wenn wir uns zum Beispiel sowas wie Java Doc anschauen, das ist einfach so ein Bündel von HTML Files, die man über einen bestimmten Pfad einfach bereitstellt. Und jetzt muss ich das irgendwie versuchen, in meinen Dokumentationsbaum, mit Einträgen. Ich habe zum Beispiel jetzt eine ganze Reihe von Beschreibungen, wo einfach in Prosa drinsteht, ich mache dieses und jenes. Und jetzt kann ich hier auf den Link klicken und bekomme dann eine Unterseite, wo ich dann praktisch auf die Java Doc weitergeleitet werden kann. Und das ist natürlich sehr schwierig, wenn meine Doku nur aus einer einzigen Datei besteht oder nur aus einer einzigen HTML Seite beispielsweise, dann ist es eben sehr schwierig, da irgendetwas in Unterbäumen mit rein zu hängen. Deswegen ist da jetzt bei uns die Anforderung gewesen, dass wir tendenziell eher eine Multi-Page Doku haben wollen, die man im Browser einfach wie eine normale Webseite benutzen kann und links einen Navigationsbaum hat, rechts dann den Content und bestimmte Einträge im Navigationsbaum führen dann zu ganz gewöhnlichen Seiten, wo in Prosa was beschrieben ist und andere führen dann zu einem Java Doc oder zu einem iOS Doc oder zu einem Open API Doc oder was auch immer noch so möglich ist. Und wenn wir diese Anforderungen an die Dokumentation genau anschauen, dann bleibt uns eigentlich gar nichts anderes übrig, als so ein Multi-Page Tool zu benutzen, was nicht das als eine einzelne HTML Datei rausrendert.

“Lucas:” Aber es gibt auch andere Gründe, so eine Multi-Page Dokumentation zu schreiben. Wenn man jetzt diese Anforderungen nicht hat, dann kann es trotzdem noch sein, dass man es vielleicht doch bevorzugt, dass man zu bestimmten Teilen der Dokumentation springt, weil ein anderer Teil überhaupt nicht interessiert. Und ich würde auch behaupten, dass die Anforderung verschiedenes Publikum für verschiedene Teile wahrscheinlich einfacher umzusetzen ist bei einer Multi-Page Dokumentation als bei einer Single-Page Dokumentation. Da müsste man verschiedene Versionen generieren oder so etwas. Da müsste man sich dann schon was bewegen. Eine weitere klare Anforderung ist auch irgendwie das Ganze zu versionieren. Zum einen möchten wir natürlich die Dokumentation selbst versionieren, weil es kommen neue Versionen von allen Komponenten raus und dann gibt es neue Versionen davon. Das heißt, wir wollen vielleicht heute die Version 1.0 des Universums herausbringen und dann nächste Woche 2.0. Aber zum anderen wollen natürlich auch unsere Dokumentation in Source Control beispielsweise versionieren, damit wir sicherstellen können, dass wir zu einer bestimmten Version zurückspringen können, oder feststellen können, wann das geschrieben wurde. Beide Arten von Versionierung spielen hier in dem Projekt durchaus auch eine Rolle.

“Lars:” Ja, genau. Und zu guter Letzt haben wir noch eine Anforderung, und zwar möchten wir auch gerne Diagramme mit anzeigen. Vielleicht mal da als Zusatz noch, dass wir die Diagramme auch editieren wollen. Und die heißt jetzt nicht, dass ich die in MS Paint aufmache und drin rummale, sondern Lucas und ich sind beide Entwickler und wir mögen gerne Text Files und dann möchten wir gerne auch in unserer IDE unserer Wahl die Diagramme bearbeiten können, dann werden die neu gerendert. Und das Gegenbeispiel, was wir schon gesehen haben, ist, dass es dann irgendwelche Diagramme gibt, die in Miro gemalt worden sind vor zwei Jahren. Dann werden die immer weiter editiert und nur wer Zugriff zu diesem Board hat, kann das dann noch irgendwie machen. Und diese Miro Diagramme, die pflanzen sich dann per PNG oder PPT fort. Das ist natürlich nicht ideal und deswegen möchten wir ganz gerne diese Sachen auch im Source Control drin haben und die sollen dann möglichst innerhalb der gleichen Tool Chain auch mit gerendert werden, ohne dass man da jetzt noch fünf Handstände machen muss.

“Lucas:” Genau. Und auch gerade Miro hat da auch noch das zusätzliche Problem, dass es oft schwierig ist, die Source von diesem bestimmten Diagramm oder von dieser bestimmten Darstellung wiederzufinden, weil alles ist irgendwie verteilt in diesem unendlich großen Scrollbalken. Das ist meiner Meinung nach noch mal so eine besondere Herausforderung bei Miro die Sachen wiederzufinden, die man da irgendwo abgelegt hat. Man weiß, es ist irgendwo, aber wo, weiß man nicht mehr. Also nimmt man den alten Screenshot, malt drauf rum und dann irgendwann endet es in Tränen. Das waren also die Anforderungen, die jetzt speziell in diesem Projekt da waren. Es kann sein, dass für euch zum Teil zutrifft oder auch nichts davon, dann ist es vielleicht gar nicht so relevant. Aber wir wollen über alle von diesen Anforderungen sprechen. Und warum du dann bestimmte Entscheidungen getroffen hast, Lars. Welchen Weg du da gewählt hast. Bevor wir das tun, sollten wir vielleicht einmal kurz einen Ausflug in die Formate machen. In welcher Sprache schreiben wir diese Dokumentation oder in welchem Tool schreiben wir die Dokumentation? Das kann man sich vorstellen wie Word oder vielleicht Markdown? Magst du dazu mal kurz was sagen?

“Lars:” Das ist natürlich jetzt grundsätzlich mal ein Trade Off. Wir als Entwicklerinnen mögen gerne sowas wie Markdown oder andere vergleichbare Formate um das in Git zu packen und das Management mag eher Confluence und Word im SharePoint, sage ich mal ganz überspitzt. Es ist einfach eine Entscheidung, die wir ganz am Anfang treffen müssen, weil danach sich natürlich sehr viel richtet und dadurch, was wir schon gesagt haben, dass unsere Dokumentation sehr technisch fokussiert ist und dass tendenziell unsere Produktleute im Projekt, die nicht schreiben, sondern das eher die Entwicklungsteams schreiben, haben wir uns entschieden, wir nehmen ein textuelles Format und haben uns dann für Markdown entschieden. Es hätte auch noch genauso gut AsciiDoc werden können oder RST oder was es da noch alles gibt. Gerade wenn man sich bestimmte Vorlagen anschaut, wie zum Beispiel arc42, da gibt es für alle verschiedenen Formate Templates. Da kann man das in Conference copy pasten oder in Enterprise Architect oder was es da nicht noch alles so gibt. Bei uns ist es dann das Markdown geworden. Grundsätzlich ist es aber auch nicht so problematisch, zwischen den Sachen später zu wechseln. Es gibt da ein cooles Tool, das nennt sich Pandoc. Pandoc ist ein universelles Dokumentations und Text Konvertierungstool. Da kann ich auf der einen Seite Markdown oder Word oder Textpress oder sogar auch LaTeX einwerfen und auf der anderen Seite kommt dann irgendein anderes Format raus. Das unterstützt weit über 20 Formate mittlerweile und wir haben uns jetzt auf Markdown committed. Und wenn wir irgendwann entscheiden: Hey, Markdown war nicht gut genug und wir müssten noch was anderes nehmen, dann jagt man das einfach alles mal durch Pandoc und dann ist es auch nicht so schlimm. Nur was wichtig ist, dass man zu jedem Zeitpunkt irgendeinen bestimmten Standard hat, dass jetzt nicht der eine Entwickler das in Markdown schreibt und die andere Entwicklerin woanders. Das wäre jetzt nicht so gut. Und die Möglichkeiten, das dann irgendwie zu exportieren, nach Confluence oder nach PDF, mit Prints oder alle möglichen anderen Tools, die stehen uns dann immer noch offen. Das ist keine Entscheidung, die uns später mal irgendwas verbaut. Es hat auch ganz viel mit dem persönlichen Geschmack zu tun. Ich kenne zum Beispiel viele Leute, die meiden Markdown wie der Teufel das Weihwasser, weil es irgendwie fünf verschiedene Markdown Parser haben, fünf verschiedene Auffassung davon hat, was Markdown ist und es ist zum Beispiel in AST deutlich besser definiert. Aber wir haben uns jetzt auf Markdown committed und damit machen wir das.

“Lucas:” Ja, absolut. Als kurze Seitennotiz. Wenn ihr euch mit solchen Konvertierungen auseinandersetzt, schaut euch mal Pandoc an. Das ist auf jeden Fall eins der Tools, das ganz fest in meiner Werkzeugkiste drin ist, das ich immer gerne mal wieder benutze, wenn ich zum Beispiel in Word Dokument erzeugen will und keine Lust habe, das in Word zu schreiben und es über Markdown schreiben will. Dafür benutze ich Pandoc zum Beispiel auch. Nicht nur für Dokumentation, sondern für alle Arten von Dokumentationskonvertierung. Eine Sache, die also der Elefant im Raum ist, wenn man über Dokumentation spricht, ist immer Confluence. Wir haben irgendwie auch oft in Projekten, Dokumentation Confluence oder es ist eine Anforderung, dass man das irgendwie zumindest Confluence zur Verfügung stellt. Auch dafür gibt es eine Lösung. Confluence Publisher. Magst du kurz erklären, was das ist?

„Lars:“ Confluence Publishing ist glaube ich ein in Java geschriebenes Tool, kommt auch von einem Kollegen von uns, der sich darum kümmert, der Christian Stettler. Das ist eigentlich ein Ding, was AsciiDoc einliest und das direkt nach Confluence exportiert. Das ist glaube ich als Docker Image bereitgestellt und dann muss man Credentials angeben. Benutzt habe ich tatsächlich noch nicht, aber ich kenne Leute, die das benutzen. Und dann schiebt man AsciiDoc auf der einen Seite rein, auf der anderen Seite kommt dann die Confluence Seiten raus, die dann auch online gearbeitet werden. Da muss man immer ein bisschen aufpassen, dass man das Editieren auf Confluence verbietet, weil das ist nur in eine Richtung nutzbar. Ich kann AsciiDoc nach Confluence konvertieren, aber ich kann dann die Änderungen nicht wieder zurück portieren in das AsciiDoc. Das heißt, wenn ich das Editieren erlaube, kann es zum Chaos führen. Das muss man also sich bewusst sein, aber ansonsten ist das eine gute Sache. Das kann man dann vielleicht auch irgendwie Teil der CI Pipeline laufen lassen und dann kommt irgendwie für den einen Teil des Projekts oder des Teams noch als Confluence Dokument raus.

“Lucas:” Und es bietet sich zum Beispiel auch an, wenn man jetzt möchte, dass die Leute, die jetzt nicht in diesen Formaten arbeiten möchten oder können, darin kommentieren können, in Confluence. Dann hat man da einen Rückkanal. Man muss eben nur aufpassen, dass man nicht irritiert wird, wie Lars schon sagt. Und da gibt es natürlich noch das weitere Universal Format für alle anderen Dokumentationen. PDF, wie kann man damit umgehen?

„Lars:“ Pandoc zum Beispiel kann PDF exportieren. Das ist gar kein Problem. Dummerweise hat Pandoc die Beschränkung, dass du eine Datei auf eine Datei mapst. Du hast eine Input Datei und eine Output Datei. Wenn du jetzt eine Dokumentation hast, die aus mehreren Files besteht, zum Beispiel mehrere Markdown Files, so wie wir das bei uns machen. Multi-Pages hatten wir schon mal angedeutet am Anfang, dann funktioniert das nicht so gut, zumal man dann auch irgendwie eine Verwirrung bekommen kann mit den Überschriftenebenen, weil dann muss man auch die Überschriftenebenen runterrechnen, von H1 auf H2 oder so was. Dafür haben wir im Projekt Prince XML eingesetzt. Das ist ein proprietäres Tool. Das gibt es als kostenlose Version für Testzwecke und man kann es auch kaufen dann, wenn man es irgendwie im Server laufen lassen will oder so. Und da kann man einfach HTML Dateien reinschieben und dann wird das irgendwie mit fancy CSS, was auch immer Rendering dann als PDF rausgehauen. Das unterstützt genau diese Multi-Page Doku. Überschriften, Schriften und interne Links kriegt der alles gebacken. Das ist in unserem Fall sehr praktisch gewesen, weil wir bestimmte Deliveries zu machen hatten, wo PDF einfach Teil der Deliverables waren. Da waren die Anforderungen im Vertrag: Ihr liefert jetzt nicht nur die Software Artefakte aus, die SDKs, sondern auch die Doku als PDF. Und dann haben wir gesagt: Das ist eigentlich blöd mit unserem Setup, mit dem Multi-Page und den verschiedenen Dingen. Dann jagen wir das einfach mal durch Prince XML durch und dann hat es funktioniert. Man könnte sich jetzt auf den Standpunkt stellen, wenn wir am Anfang zum Beispiel AsciiDoc benutzt hätten, wäre das auch direkt gegangen, weil AsciiDoc so includes kann und so was. Aber AsciiDoc hat den Nachteil, dass dann tendenziell immer nur eine einzelne HTML Seite rauskommt. Und wir wollten eigentlich im Browser mehrere Seiten haben, dass wir eine bestimmte Hierarchie haben, aber dann als PDF dann nur ein monolithisches PDF. Vielleicht ist das einfach nur eine super ungewöhnliche Kombination von Anforderung bei uns gewesen, aber für uns hat diese Tool-Kombination dann funktioniert, um das umzusetzen.

“Lucas:” Also würdest du generell sagen, dass AsciiDoc sich mehr anbietet für Single-Page und Markdown für Multi-Page Dokumentation?

“Lars:” Ja, würde ich so unterschreiben. Natürlich gibt es da ganz viele Fußnoten dazu. Aber tendenziell habe ich die Beobachtung gemacht, dass AsciiDoc Dokumentationen eher Single-Page ist.

“Lucas:” Fußnoten gibt, es glaube ich im Standard Markdown nicht, aber egal.

“Lars:” Im AsciiDoc schon.

“Lucas:” Kurz zu der Tooling Frage. Wir haben uns jetzt für Markdown entschieden, wir wollen Multi-Page. Jetzt hast du dich dafür entschieden, ein Static Site Generator zu nehmen als Tool für dieses Ding und du hast dich für Jekyll entschieden. Magst du dazu mal erklären. Warum ein Static Site Generator und warum speziell Jekyll?

“Lars:” Für den Static Site Generator war die ganz einfache Überlegung, dass wir eine möglichst leichtgewichtige Server Komponente haben. Da können wir dann später auch noch mal darüber reden, wie der Server genau ausschaut. Wir wollten aber jetzt nicht irgendein CMS hernehmen, was einen großen Server braucht, vielleicht Datenbank und sonst irgendwie so ein Kram. Wir haben gesagt: Wir haben Text Files, die liegen im Git und was bietet sich da besser an als Static Site Generator? Ich glaube, das ist eigentlich ein No Brainer, diese Entscheidung gewesen. Und für Jekyll haben wir uns entschieden, aus mehreren Gründen. Das eine ist natürlich, dass Jekyll super konfigurierbar und erweiterbar ist. Man kann in Jekyll Tausende von Plug-ins anziehen, die man auch gegebenenfalls schnell selbst schreiben kann. Da muss man ein bisschen Ruby Code schreiben, aber dann kann man das sehr leicht erweitern. Aber es gibt eben auch eine große Bibliothek von existierenden Plug-ins. Zum Beispiel konnten wir sehr einfach Bibliografien einbinden mit BibTex, also haben wir über BibTex Files geschrieben. Das ist so ein Format für LaTeX, wer das nicht kennt. Da kriegt man aus allen möglichen Metadatenarchiven die BibTeX Files raus, wenn man die Bücher zitiert oder sonst für Zeug. Und das kann man dann einfach per Plug-in anziehen und dann kann man einfach BibTeX Verweise benutzen. Jekyll kann Markdown. Da ist auch eine Template Sprache mit dabei, die nennt sich Liquid und ist eben dadurch sehr universell einsetzbar. Der große Nachteil an Jekyll ist, dass es nicht besonders leichtgewichtig zur Buildzeit ist. Es erfordert ganz viel Ruby Code, der da ausgeführt wird. Deswegen gibt es da sehr viele Konkurrenten dazu. Ich glaube, der größte Konkurrent ist wahrscheinlich Hugo, was in Go geschrieben ist, was nur eine einzige Binary ist, die man einfach in das Git mit reinkopieren kann und dann ist man glücklich. Aber im Vergleich zu Jekyll kann Hugo einfach fast nichts. Da gibt es das nicht dieses riesige Plug-in Ökosystem, wo man zusätzliche Dinge tun kann und da sind wir auch schon wieder bei unseren Anforderungen. Wir hatten gesagt, wir wollten eigentlich so was wie Diagramme mit einbinden, die wir aus Textdateien oder sonst irgendwo generieren. Und das ist super einfach in Jekyll zu machen, dass ich einen eigenen Block definiere, wo ich zum Beispiel sage: Das, was jetzt hier in diesem Block drinsteht, ist kein Markdown, sondern das ist zum Beispiel PlantUML oder irgendwas anderes. Und dann kann ich mich praktisch in die Bild Pipeline von Jekyll mit reinhängen und kann da ein eigenes Tool aufrufen, was dann diesen Text in ein PNG oder in SVG konvertiert. Das ist super einfach damit zu lösen. Das Einzige, was man damit nicht so richtig machen kann, ist irgendwie so ‘what you see is what you get’ editing. Wenn ich jetzt zum Beispiel doch sage, die Leute, die eher nicht technisch sind, sollen damit irgendwas machen, haben dann vielleicht Schwierigkeiten damit, weil man muss dann wirklich Markdown Files mit dem normalen Editor bearbeiten und lässt man das durch Jekyll durchlaufen und es kommt was raus. Es gibt tatsächlich ein Plug-in, wo man einen browserbasierten Editor bekommt. Man kann das Jekyll Tool starten, vielleicht per Docker oder was auch immer. Dann bekommt man so einen Button, wo man auf Edit drückt und dann kriegt man so eine Art Markdown ‘what you see is what you get’ halb Editor. Hatten wir auch mal drin tatsächlich, hat sich aber keiner dafür interessiert. Deswegen haben wir es dann wieder ausgebaut. Sowas ginge tatsächlich mit Jekyll. Ob man es braucht ist wieder eine andere Frage.

“Lucas:” Ja, absolut. Ich glaube, wir sollten vielleicht nochmal ein bisschen näher noch auf die Grafik Tools eingehen, weil ich finde, das ist auch sehr elegant gelöst, dass man eben innerhalb von einem Markdown Dokument direkt ein Diagramm beschreibt. Kannst du kurz erklären, wie man das benutzt erst mal? Nicht wie: Wie hast du das gelöst? Sondern wie schreibt man jetzt die Doku mit diesem Ansatz?

“Lars:” Das ist ein sogenannter Liquid Filter. Ich glaube die Dinger heißen Filter oder Blöcke, ich bin mir nicht ganz sicher. Man schreibt einfach {% plantuml %}. Die Tags in Liquid sind mit geschweiften Klammern und Prozent, dann fängt man mit PlantUML an, macht man den Block auf, dann kommt der PlantUML Text, der in einer speziellen Syntax ist und dann kommt noch mal ein {% endplantuml %}. Es ist nicht so ganz richtig, aber es so eine eigene Liquid Blocksprache, wie auch immer. Und das tut man dann einfach in diesem Block seinen eigenen Custom Code reinschreiben und dann funktioniert es automatisch. Da muss ich als Autor:in von der Doku nichts Besonderes machen.

“Lucas:” Was ich daran sehr praktisch finde als einer der Autoren dieser Dokumentation, ist, dass ich in einem Commit ganz klar auch sehen kann, im diff: Ich habe hier Text geändert und den dazu passenden Teil des Diagramms, so dass das ein diff ist. Das ist eben das, was in vielen anderen Tools nicht so gut funktioniert, weil da dann in dem diff drinsteht: Hier wurde Text geändert und das Binary wurde durch ein neues Binary Text ausgetauscht. Dann kann man nicht sehen, was sich da genau verändert hat. Und das ist sehr übersichtlich, finde ich. Dadurch, dass es wirklich einfach innerhalb von einem Dokument ist und das eben dann wieder lesbar ist, Files in PlantUML beispielsweise geschrieben ist und wenn sich dann der Klassenname ändert, ändert es sich oben im Text, aber ändert sich unten auch in dem Diagramm. Und damit ist, fällt es mir zumindest leichter, da auch immer up to date zu bleiben bei dem, was wir da beschreiben, weil eben alles aus einem Guss ist. Das finde ich sehr angenehm als Autor. Und wie hast du es gemacht? Wie hast du es hinbekommen?

“Lars:” Ein bisschen Ruby Code und Spucke würde ich mal sagen. Es gibt existierende Plug-ins für PlantUML und für andere Sachen in Jekyll, die haben aus verschiedenen Gründen nicht 100 % das getan, was ich wollte. Ich wollte auch Caching. PlantUML ist in Java gebaut, da muss man für jede Konvertierung eine JVM starten, das ist alles ein bisschen schwergewichtig. Deswegen wollte ich das cachen und lauter so Dinge. Dann habe ich mir einfach schnell ein Plug-in selbst geschrieben. Das sind 30, 40 Zeilen Ruby Code, die man dann einfach in das Plug-ins Unterverzeichnis reinkopiert. In unserem Doku Git gibt es einfach einen Unterordner, der heißt Plug-ins. Da ist eine Ruby File drin, die heißt PlantUML.rb und darin registriere ich eine Liquid Handler für diesen PlantUML Block und der wird dann einfach ausgeführt, automatisch, wenn ich so ein PlantUML Block sehe. Und darin checke ich zum Beispiel, ob ich den Text schon mal gesehen habe, ob ich den im Cache drin habe und wenn nicht, dann schreibe ich das in eine temporäre File, lasse PlantUML darauf laufen und kopiere dann das Resultat wieder wo hin, wo ich es brauche. Das ist echt nicht so schwierig. Und das gleiche dann nochmal für GraphViz. GraphViz ist ein Tool, was, wie der Name schon sagt, Graphen visualisiert und damit haben wir eigentlich schon ganz viel abgedeckt. Es hätte tatsächlich noch die Alternative gegeben, sowas wie Mermaid.js zu benutzen, was Client-seitig gerendert werden könnte. Nur ist Mermaid.js allerdings sehr eingeschränkt und konnte bestimmte Diagrammtypen, die wir wollten oder bestimmte Visualisierungstypen, die wollten einfach nicht. draw.io gibt es auch noch. Das ist, soweit ich weiß, auch in JavaScript implementiert, könnte man wahrscheinlich auch Client-seitig machen, haben wir aber noch nicht mit integriert. Mit PlantUML und GraphViz kommen wir eigentlich schon sehr weit und können viele Dinge machen, die wir brauchen.

“Lucas:” Aber an der Stelle einfach der Hinweis, dass man eben solche Plug-ins relativ einfach schreiben kann und dem dann einfach irgendwelchen Text übergibt und sagt: Hier hast du bisschen Text, bitte gib mir doch ein Bild zurück und dann bindet man das an der Stelle ein. Das Prinzip trifft quasi auf alle davon zu, außer die, die vielleicht HTML erzeugen müssen, auf dessen Basis dann irgendein JavaScript im Browser macht, aber das wäre trotzdem ein sehr ähnliches Prinzip. Irgendein Konvertierungsschritt von einfach einem Textteil, der eben nicht Markdown ist, sondern eine andere Sprache, die einfach im Markdown eingebettet ist.

“Lars:” Man muss dazu sagen, ich habe keine Ahnung von Ruby. Eigentlich ist der Lucas unser Ruby Experte, macht aber gar kein Ruby in dem Projekt und ich habe das tatsächlich geschafft, ohne Lucas Hilfe diese Plug-ins zu bauen. Lucas hat ein bisschen Code Review gemacht und hat gesagt, dass ich bestimmte Sachen einfach nicht idiomatisch geschrieben habe. Aber es ist auch für jemanden wie mich, der keine Ahnung von Ruby hatte, problemlos möglich gewesen einen Plug-in zu schreiben.

“Lucas:” Und eine andere Anforderung, über die wir gesprochen haben, waren noch die Quellen. Dass wir da in diesem Projekt beispielsweise jetzt einen Java Doc von der Android SDK einbinden wollen oder eine iOS SDK Beschreibung. Wie hast du das denn gelöst?

“Lars:” Javadoc ist eigentlich total easy. Das ist einfach ein Bündel von HTML Files, die kann ich irgendwo in einen Unterpfad reinkopieren und der benutzt automatisch schon relative Pfade und da brauche ich eigentlich nicht großartig was machen. Dann setze ich einfach nur irgendwann einen bestimmten Link, muss dann schauen, dass der Link dann auch im Navigationsbaum auftaucht und damit habe ich das Problem gelöst. iOS ist super schwierig im Vergleich dazu, weil die offizielle Art und Weise wie Apple iOS Doku publiziert ist über dieses DocC Tool, was bei Swift mit beiliegt. Und das macht Client-Site Rendering, zwingenderweise und erfordert bestimmte absolute Pfade. Das heißt, wir mussten das in der ersten Iteration, wie wir das gemacht haben, auf eine separate Subdomain auslagern. Da hatten wir dann also docs.coolproduct.com und dann hatten wir ios.doc.coolproduct.com und mussten dann auch noch bestimmte Pfadregeln setzen in unserem HTTPS Server, damit das korrekt ausgeliefert wird. Das war richtig anstrengend. Das hat glaube ich zwei Tage gedauert, bis wir das richtig hingekriegt haben. Mittlerweile sind wir davon weggekommen. Wir benutzen nicht mehr DocC, sondern wir benutzen Jazzy, was letztendlich nichts anderes macht, wie Javadoc auch. Und zwar einfach ein Bündel von HTML Files, die man einfach ausliefern kann. Der Nachteil ist, das Jazzy ist nicht so optisch ansprechend wie DocC. Damit können wir aber leben, weil das wie gesagt keine Seite ist, die irgendwelche End-User:innen sich anschauen, sondern das ist für Entwickler:innen gedacht und es ist nicht unbenutzbar, was bei Jazzy rauskommt. Es ist funktional, sage ich mal, aber nicht besonders hübsch. Dafür können wir es super einfach einbinden. Die Zusatzschwierigkeit, die wir jetzt bei sowohl bei Javadocs, Kotlin, iOS hatten, war, dass wir noch diese Versionierung drin haben. Das haben wir dann dadurch gelöst, dass wir einfach verschiedene Unterordner anlegen für verschiedene Versionsstände. Zum Beispiel einen Unterpfad Mobile/1.0.1, /1.0.2 und so weiter, dann einfach drumherum gepackt haben, eine Versionsauswahl, HTML Struktur, wo ein iFrame ist, was dann tatsächlich dann die Version anzeigt. Das heißt, ich habe oben ein Dropdown, wo ich die Versionen auswählen kann und unten bekomme ich dann im iFrame das entsprechende Teil reingerendert. Das ist tatsächlich ein bisschen mit Client Code. Es wird mit JavaScript gemacht und ich muss dann zur Buildzeit von der Doku dann schauen: Was habe ich denn für Versionen um dann die Dropdown Box zu füllen? Und im Browser wird dann, wenn ich in der Dropdown Box das selektiere, zum Beispiel 1.0.1 selektiere, wird dann das iFrame upgedatet und dann die Javadoc Files aus dem entsprechenden Unterordner herausgeholt und angezeigt. Das ist ein Kompromiss, den wir gemacht haben zwischen Logik auf dem Server und Logik auf dem Client. Und ich glaube, das ist verschmerzbar, wenn man da so ein bisschen Client-Site Logik hat an der Stelle.

“Lucas:” Aber wie funktioniert es dann für den Export von PDF? Ist das dann auch mit enthalten oder nicht?

“Lars:” Das kommt darauf an. Manche API Docs könnten wir theoretisch exportieren, so was wie Open API, was auch eine Seite ist. Bei so Sachen wie Kotlin Doc oder Javadoc tun wir uns da sehr schwer, weil das sind tendenziell sehr viele Seiten, die dann im PDF rauskommen. Wir haben uns dann also deswegen darauf geeinigt, dass wir die tatsächlichen Codedokumentation nicht mit dem PDF Export mit drin haben, sondern nur High Level Documentation und auch so was wie HTTP Schnittstellen. Das kann man problemlos machen, aber wenn es dann wirklich um Java SDKs geht, wird es wirklich schwierig das als PDF zu rendern. Und das ist ein generelles Problem. Es ist jetzt nicht ein Problem, was wir mit Jekyll haben, sondern das hätte man mit allen anderen Tools wahrscheinlich auch, so SDK Doku in eine einzelne Datei zu exportieren.

“Lucas:” Absolut, aber eine ganz besondere Anforderung, über die wir direkt am Anfang gesprochen haben, war eben diese verschiedene Dokumentation für verschiedenes Publikum. Wie funktioniert das denn jetzt in dem Jekyll Ansatz?

“Lars:” Wenn ich jetzt einfach nur Dateien rendern will oder Dateien nicht rendern will, also einfach bestimmte Dateien an- und ausknipsen will, kann ich das in der Jekyll Config machen, kann einfach sagen: Exclude und dann gebe ich ein Array von Files an, die ich nicht brauche. Das haben wir so implementiert, dass es verschiedene Sub Configs gibt. Und wir wählen dann zur Buildzeit einfach die richtige Sub Config aus, welche Dateien drin sind, welche Dateien draußen sind. Und wenn ich tatsächlich auf einer einzigen Seite, in einem einzigen Markdown Dokument was anderes rendern will, muss ich so was ähnliches machen wie ifdef. Da kann ich auch in Liquid dann If-Blöcke machen und da muss man aufpassen, dass man es ein bisschen sparsam macht, dass das dann nicht unübersichtlich wird. Aber das ist generell ein Problem, was auch an vielen anderen Stellen auftritt, wenn man so Layouting macht oder so Rendering, dass man bestimmte Teile anzeigt und andere nicht. Je nachdem, was man für eine Config hat. Und ich sage mal so, es ist jetzt nicht besonders toll, aber es geht schon. Und was ich witzig fand, vor nicht allzu langer Zeit gab es eine Ausgabe vom Newsletter von Hillel Wayne, der diesen Ansatz Meta Files genannt hat. Der hat das Problem für ein Buch, was er schreibt, dass er irgendwie ein bestimmtes Codebeispiel hat, was er Schritt für Schritt aufbauen will. Er fängt praktisch an mit einem super einfachen Beispiel und dann kommt dann noch eine Komplikation hinzu und so weiter und immer so weiter, bis er dann beim fertigen Beispiel ankommt. Und er hat sich das auch so auf XML Basis zusammengebastelt, dass diese eine Datei mehrere verschiedene andere Dateien raus generieren kann. Er nennt das ganze Meta Files. Ich weiß nicht, ob das jetzt ein allgemein akzeptierter Begriff ist, aber letztendlich verfolgen wir den gleichen Ansatz und es ist pragmatisch, mit dem geringsten Aufwand, wie wir das beste Ergebnis erzielen konnten.

“Lucas:” Aber ich würde trotzdem behaupten, dass es in dem Projekt zumindest so ist, dass der Großteil von dem Branching auf Dateien basiert. Dass man eben sagt: exkludiere bitte diesen Dateibaum, sage ich jetzt mal.

“Lars:” Zum Beispiel: exkludiere alles, was unter Export Control steht. Und das können wir mit Jekyll super einfach machen. Da fügen wir einfach einen Key in dem Exclude mit dazu.

“Lucas:” Und ich will jetzt auch mal behaupten, dass für viele, die so eine Anforderung haben, das vermutlich schon alle Probleme löst. Dass man jetzt innerhalb von einer Datei da aufteilen muss, ist das wirklich eine Seltenheit und wenn es dann ein bisschen unschön wird, wie es dann aussieht, kommt es jetzt auch nicht so wild. Wie du sagtest, man sollte das vielleicht nicht übertreiben und dann irgendwie jeden Paragraphen einzeln nochmal für jede Dokumentation schreiben. Da sollte man sich dann einfach noch mal überlegen, ob man da nicht vielleicht eine zweite Datei anlegt und die eine Datei inkludiert in den Baum und die anderen in den. Das könnte dann einfacher werden.

“Lars:” Genau, der Vollständigkeit halber will ich noch erwähnen, dass das auch in AsciiDoc kein großes Problem ist, obwohl man da meistens so ein Single-Page Output bekommt. Weil AsciiDoc hat auch so conditional includes. Das wäre damit auch kein Problem gewesen. Wir haben jetzt einfach Markdown mit mehreren Dateien und können dann die Dateien an- und ausknipsen. In AsciiDoc kann ich in Imports oder Includes an- und ausknipsen. Eigentlich gleiches Prinzip.

“Lucas:” Ja, genau. Und die letzte Anforderung war noch die Zugangskontrolle. Auch dazu hast dir noch ein bisschen was ausgedacht, oder bzw. musstest du ein bisschen rumhacken, sage ich jetzt mal vorsichtig. Was musstest du denn da machen?

“Lars:” Wir wollen Doku natürlich nicht ins Internet einfach so reinhängen, dass das sich einfach von irgendwelchen Leuten angeschaut werden kann, sondern wir wollten das mit dem SSO verbergen. Das haben wir mit einem Keycloak im Projekt gelöst. Eigentlich eine relativ Standard SSO Lösung. Und die Idee ist, dass dann irgendwie ein sidecar oder was auch immer sich dann darum kümmert, dass überhaupt nur eingeloggte User sich das anschauen können, das ist also nichts, was wir tun mussten. Was wir aber tun mussten ist, wir mussten einen Logout Button anzeigen. Darauf hat einfach die Compliance Abteilung bestanden, dass wenn man sich irgendwo einloggen kann, man sich auch ausloggen können. Das ist das Problem, dass der Logout Link zur Laufzeit erst bekannt ist. Es ist ein riesiger Kubernetes Cluster und da ist jetzt unsere Doku ein einziger Container mit einem nginx drin, da sind die ganzen HTML Files drin und dann bekommt dieser Container zur Bootzeit, also nicht zur Doku Buildzeit, sondern zur Container-Startzeit erst gesagt, was jetzt die Signout URL ist. Und das haben wir mit einer steinalten Technologie gelöst, die sich Server-site Include nennt, SSI. Und dann kann ich einfach in meinem HTML Template, was ich für alle Unterseiten benutze in der Doku, einfach so eine Art Printline machen. Und dann kann ich einfach so den Wert einer Umgebungsvariable printen. Wenn ich auf den nginx draufgehe, dann liest er die Umgebungsvariablen und printet den Inhalt dahin. SSI ist glaube ich eine super alte Technologie und es hat auch super komische Syntax. Aber es macht genau das, was wir brauchen in dem Fall.

“Lucas:” Wenn ihr euch noch mal für andere Use Cases für SSI interessiert, haben wir auch mal eine Folge aufgenommen zum Thema Transklusion, da kann man auch SSI für benutzen. Auch wenn es steinalt ist, ist es immer noch eine sehr nützliche Technologie, die man häufiger mal benutzt. In anderen Use Cases benutzt man dann vielleicht eher ESI, das ist im Prinzip eine Weiterentwicklung von SSI, vereinfacht gesagt. Aber für den Fall war es genau das Richtige, weil es eben das ist, was man auch in nginx oder Apache sehr gut benutzen kann, weil das eben eine statische Seite einfach ist. Und das ist genau das Richtige.

“Lars:” Ich will vielleicht noch kurz zum Abschluss mal den Punkt nginx vs. Apache aufgreifen, weil du es eben schon genannt hast. Wir haben nginx benutzt, weil es einfach alle benutzen und weil es sehr leichtgewichtig ist. Der große Nachteil ist, dass nginx nur sehr eingeschränkt konfigurierbar ist. Insbesondere erlaubt er sowas wie .htaccess nicht. Das heißt, immer wenn ich irgendwelche Rewrites oder Redirects machen will, muss ich das irgendwie statisch in die Config reinschreiben. Ich bin persönlich so der Apache Fan, aber man kriegt das schon auch mit nginx alles irgendwie gelöst. Und es wird von allen möglichen Leuten hergenommen. Das heißt, man fährt da auf jeden Fall nicht schlecht, weil es gibt da Support und regelmäßige Sicherheitsupdates und alles einfach. Und Apache ist eher so ein bisschen verschrien, weil man sagt, das ist zu schwergewichtig und das kann alles Mögliche, aber es kann auch .htaccess, was nginx leider nicht kann.

“Lucas:” Nur, damit da keine Missverständnisse aufkommen. Ich würde sagen, sowohl nginx als auch Apache kriegen beide sehr regelmäßig Sicherheitsupdates. Da tun die sich glaube ich nicht großartig.

“Lars:” Ach so, ja, das wollte ich jetzt nicht implizieren, dass Apache kein Support hat.

“Lucas:” Ich glaube, was Support und Dokumentation angeht, sind die beiden schon sehr gut aufgestellt als sehr große, sehr verbreitete Tools.

“Lars:” Aber mein Punkt war glaube ich so, wenn wir jetzt irgendwie als Ingress Controller in der kybernetischen nginx hernimmst, ist das deutlich einfacher als wenn man Apache hernimmst. In der Cloud Native Community ist nginx einfach extrem viel verbreiteter als Apache.

“Lucas:” Weil ich persönlich behaupten würde, dass nginx einfacher ist als Reverse Proxy zu benutzen, aber Apache hat noch ein bisschen Stärke, was einfach statische HTML Seiten ausliefert. Da ist Apache immer noch sehr mächtig. Als allerletzten Punkt, bevor wir hier ein Strich drunter machen, würde ich noch kurz auf den Trade Off eingehen. Du hast gesagt, wir machen es mit Markdown, wir schreiben Markdown, in Markdown benutzen jetzt gleich auch noch Liquid Syntax. Das sind solche Sachen, da gibt es bestimmte Leute, die kriegen quasi Herzaugen, wenn sie das hören, weil sie sagen: Wahnsinn, das ist genau das, was ich möchte. Und andere Leute, kriegen quasi einen kalten Schweißausbruch, weil sie sich nicht vorstellen können, mit so einem Tool zu arbeiten. Und das haben wir tatsächlich auch in diesem Projekt. Es gibt ein paar Leute, die würden viel lieber das alles in Confluence schreiben und niemals dieses Markdown anfassen und andere, die würden niemals Confluence anfassen, die wollen lieber in so einem Tool das schreiben. Und diesen Thread, da muss man sich einfach in seinem Projekt entscheiden. Was ist denn das, was wir brauchen? Wer möchte diese Dokumentation schreiben und wie stehen die zu diesen verschiedenen Ansätzen? What you see is what you get in Confluence vs. Code as Documentation, in so etwas wie einem Static Site Generator. Und wir haben uns jetzt anhand der Leute, die in dem Projekt sind, dafür entschieden, diesen Ansatz zu verfolgen. Aber in einem anderen Projekt könnte das eben tatsächlich ganz anders aussehen, wo das überhaupt nicht passt. Und das nur so als Warnung vor diesem Trade Off. Leute, die sowieso schon ganz viel Markdown schreiben, für die ist das sehr einfach zu erlernen, da jetzt noch rauszufinden, wie man ein Diagramm integriert. Für Leute, die sowieso schon mit Markdown eher Schwierigkeiten haben, vielleicht auch nicht so gerne mit Git arbeiten, ist das vielleicht nicht der richtige Ansatz. Da sollte man sich einfach bewusst sein, bevor man die Entscheidung trifft.

“Lars:” Ein Punkt zum Beispiel, den wir jetzt auch gar nicht genannt haben. Es gibt auch noch Sachen dazwischen. Es gibt auch noch durchaus Content Management Systeme, die nicht Confluence sind und da auch bestimmte Sachen unterstützen. Jetzt mal ganz blöd gesagt, man könnte auch die Doku in Wordpress reinpacken. Das wäre sicherlich eine Option. Das hat natürlich auch wieder andere Vor- und Nachteile. Wir wollen jetzt auf keinen Fall sagen, dass es jetzt nur diese zwei großen Stacks gibt, nämlich Git und Markdown auf der einen Seite und Confluence auf der anderen Seite. Und dann gibt es noch ganz viele anderen Stacks, die unterschiedliches Tooling haben und unterschiedliche Zielgruppen bedienen und so weiter. Was wir hier machen konnten im Podcast ist eigentlich nur einen sehr kleinen Einblick geben in diese Welt der Entscheidungen, die wir da treffen konnten.

“Lucas:” Absolut. Aber so klein war die Übersicht auch nicht. Ich glaube, wir kommen jetzt trotzdem langsam mal zum Schluss ich. Ich danke dir, Lars, für diese Übersicht. Ich glaube, das wird schon ein paar Leuten helfen, vielleicht die Probleme zu lösen, die sie in ihrem Projekt mit der Dokumentation haben. Dann sage ich schon mal den Hörerinnen und Hörern, bis zum nächsten Mal. Auf Wiedersehen!

“Lars:” Tschüss.