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:


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:

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.

Kommentare, Feedback und andere Anmerkungen? Schreib mir auf Mastodon oder eine E-Mail 🤓