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.

Dyson V8

Ich mag ja die „Stuff that works“ -Posts aus dem Blog von Volker Weber sehr. Hier also mein erster offizieller Beitrag zu dieser geklauten Kategorie!

Ich bin allgemein kein großer Freund davon, den Boden zu staubsaugen, daher zog ja schon vor ein paar Jahren der Roomba ein. Leider kriegt der nun auch nicht alles mit und ab und zu braucht man ja doch mal spontan einen Sauger um punktuell, oder einfach schnell und gezielt etwas sauber zu bekommen.

Früher hieß das: den Staubsauger aus der Abstellkammer friemeln, Rohr dran stecken, Kabel komplett rausziehen, Steckdose finden, Stecker rein, lossaugen, Saugkraft variieren, weil viel zu laut (oder mit Noise Cancelling saugen). Am Ende fehlen leider wieder einmal zwanzig Zentimeter Kabel und man muss doch nochmal umstecken.

Da kommt der Dyson V8 ins Spiel. Er hat nämlich einen sogenannten Akkumulator mit Lithium-Ionen-Technologie! Kaum zu glauben. Hochmoderne Technik, die man sonst nur aus Teslas und Flugtaxis kennt, verkleinert und in Staubsaugerform gepresst!

Spaß beiseite, der Dyson hat eine wunderbar platzsparende Wandhalterung, in der er automatisch geladen wird, man nimmt ihn raus, saugt die gesamte Wohnung, weil es so schön einfach ist und hängt ihn wieder auf, fertig. Die Akku-Laufzeit ist mit irgendwas bei 30 Minuten angegeben, allerdings auf niedriger Stufe (reicht aber) und ohne Aufsatz, was totaler Quatsch ist, aber ich habe regelmäßig noch 1-2 der 3 Akkubalken übrig, nachdem ich die 80 Quadratmeter gesaugt habe.

Ja, es gibt auch den V10 und mittlerweile sogar den V11. Beide saugen ein bisschen besser und länger. Kosten aber auch mehr. Ich empfand den V8 zum Kaufzeitpunkt als Preis-Leistungssieger und kann ihn bisher uneingeschränkt empfehlen!

(Das Einzige, was mir nicht so gefällt, ist, dass das Dyson-Plastik immer so billig aussieht und auch von der Haptik irgendwie nicht zufriedenstellend ist)