knuspermagier.de
Der privateste Blog von Philipp.

Technische Dokumentation mit Markdown und Pandoc

Eine der wenigen Dinge, die ich in meinem Informatikstudium lernte, war es, mit LaTeX umzugehen. Warum sollte man sich auch außerhalb des Studiums mit so einem Käse beschäftigen.

Zwei Dinge sind allerdings hängen geblieben:

  • Man hat auf jeden Fall ein elitäres Gefühl, wenn man es auf Anhieb schafft mit der richtigen Anzahl und Reihenfolge von pdflatex-Aufrufen eine PDF zu erzeugen
  • Man kann damit echt schicke PDFs machen, mit vielen Funktionen, ohne dass man einen verdammten Word-Processor anwerfen muss!

Bei einem Kundenprojekt war es nun mal wieder an der Zeit, dass ein Dokument geschaffen werden musste, in dem ein paar Dinge stehen und das am Ende auch zum Kunden muss. Das letzte Dokument dieser Art hatte ungefähr 40 Seiten und liegt als Google Docs-Datei im Drive. Es dauert ungelogen 1-3 Minuten, bis die Datei auf meinem hunderttausend Euro MacBook bearbeit- oder durchsuchbar ist.

An uns für sich bin ich ja ein Freund von Google Docs. Also abgesehen davon, dass es Google ist. Früher war Google ja noch lieb. Aber sobald man größere Dokumente darin verwaltet, die dann noch ein paar Bilder oder Tabellen enthalten, kann man sich, während das Ding lädt auf jeden Fall einen Kaffee machen.

Da ich diese Art meine Zeit zu verbringen, also das Warten, nicht die Zubereitung von Kaffee, oder viel mehr das Versauen des Milchschaums, und danach wirklich unglückliche Gestalten von Latte Art, ziemlich verabscheue, kam ich auf die Idee mich mit einer anderen furchtbaren Beschäftigung zu bestrafen. LaTeX. Still better than Warten.

Glücklicherweise verlor ich bereits nach wenigen Sekunden die Lust daran, als ich die ersten Backslash-Kommandos sah.

Aber wie wäre es denn mit Markdown? Markdown! Kann man damit wohl eine geile PDF erstellen, die man dem Kunden schicken kann? Klar! Wie? Mit LaTeX!

Also, zumindest gibt es ein Tool namens Pandoc, das alle möglichen Arten von Dokumenten ineinander konvertieren kann. Will man PDFs erstellen ist dann auch immer irgendwie LaTeX drin verwickelt, aber man bekommt davon nicht viel mit. Perfekt!

Ich fing also an, die grobe Dokumentenstruktur zu bauen, schrieb ein bisschen und fügte ein paar Grafiken ein. Alles lief ganz gut. Ich investierte noch ein paar Minuten um das PDF grob in unser CI zu drücken und war eigentlich ganz froh, bis ich bemerkte, dass die Art Dokument, an dem ich arbeite viele Tabellen enthält.

Tabellen waren damals schon der Endgegner. Die LaTeX-Syntax für Tabellen ist furchtbar. Nun ist es leider so, dass Tabellen mit viel Inhalt auch in Markdown nur eher nervig pflegbar sind, zumindest wenn man das Markdown in einem normalen Editor schreibt, der da jetzt keinen oberfancy Editiermodus dafür hat.

Zudem gesellen sich natürlich andere Nachteile dazu:

  • Alle anderen Dokumente sind in Google Drive.
  • Das Kollaborieren, Kommentieren, Änderungsvorschläge machen ist in Google Docs doch eine Ecke komfortabler als über Merge Requests in GitLab.
  • Niemand hat Lust sich mit Pandoc oder LaTeX-Problemen rumzuschlagen, wenn doch mal was nicht klappt, oder eine Tabelle aus dem Layout fällt, obwohl man eigentlich alles richtig machte!

So endete mein kurzer Ausflug in eine potentiell Google-freiere Welt. Mein kurzer Traum mit meinen Kollegen die technischen Konzepte am gleichen Ort zu dokumentieren und zu reviewen wie den Code und mein schmerzlich vermisstes Gefühl der LaTeX-Beherrschenden Elite anzugehören. Alles zerstört von ein paar Tabellen.

Und naja, auch weil ich mir nicht länger als 30 Minuten Zeit nehmen wollte, das jetzt mal auszuprobieren.