CLI-Adventskalender: Dokumentation

Bitte noch nicht den Tab zumachen – ich weiß, Dokumentation klingt ungefähr so spannend wie Hausaufgaben in katholischer Religionslehre mit dem Thema Kirchengeschichte im frühmittelalterlichen Oberbayern. Aber im 19. Post des CLI-Adventskalenders habe ich ein paar Sachen gesammelt, um mit einfachen Mitteln viele Schmerzen zu vermeiden.

„Faulheit siegt.“

Besser?

Ich vermute stark, dass die Leser dieses Artikels in polare Lager aufgeteilt sind: Einmal die Leute, für die Sachen zu dokumentieren etwas ist, was bitte andere Leute im Team machen sollen. Und auf der anderen Seite die Leute, die ständig auf der Suche sind, diesen Prozess effizienter zu gestalten.

Warum Dokumentation ätzend ist

Wie viel muss ich jetzt schreiben? Wie untechnisch/technisch soll es sein? Ändert sich das nicht ohnehin wieder in drei Wochen? Es gibt mir hier auch wirklich niemand Feedback. Ich habe selber eigentlich so überhaupt keine Ahnung von diesem Thema.

Kommen euch diese Gedanken vertraut vor?

Lasst es mich mal strukturiert aufzählen. Sachen die Dokumentation aufwendig machen können:

• Unklarer Scope: Was gehört alles dokumentiert? Was genau bedeutet Architekturskizze zum Beispiel? Zeige ich Maschinen? Pods? Klassen? Methoden?
• Unklare Zielgruppe: Für wen schreibe ich hier? Muss ich erklären was eine Datenbank ist? Was unsere Firma tut? Was in Klasse X vor sich geht?
• Mangelndes Vorwissen: Wenn ich für jeden Abschnitt eine Stunde recherchieren muss.
• Lange Feedbackzyklen: Das Team ist mit eigenen Tickets beschäftigt, reagiert nur langsam auf Fragen.
• Unklarer Sinn: Wozu brauchen wir das überhaupt? Wird das irgendjemand lesen?
• Kurze Halbwertszeit, Sisyphos-Effekt: Man könnte argumentieren, dass das das Ergebnis aus den oberen Punkten ist.

Das sind die Punkte, an denen ich mich hier orientieren werde.

Die Zielgruppe bist erstmal Du

Damit frühstücken wir eine ganze Reihe der Punkte ab.

• Unklare Zielgruppe? So lange wir selber verstehen was hier vor sich geht, können wir das Wissen auch an andere übertragen. „Explain like I’m 5“ ist der ultimative Test des eigenen Verständnisses (und eine fantastische Lerntechnik für die Erklärenden).
• Mangelndes Vorwissen? Schaffe es Dir. Das ist der lohnenswerteste Teil der Dokumentation. Wissen schaffen und abrufbar machen.
• Lange Feedbackzyklen? Führe die Befehle selber aus (z. B. bei Onboarding Guides), quizze Dich selbst mit Architekturfragen und versuche, sie anhand der vorhandenen Skizzen zu beantworten. Gehe einmal quer durch die Codebasis und versuche Komponenten zu finden, die sich nicht von den bunten Diagrammen vertreten fühlen.
• Außerdem zu langen Feedbackzyklen: Stelle Deine Fragen rechtzeitig. Wirf kurze Textabschnitte zu Experten hin. Nerv sie. Wenn es wichtig genug ist, dass Du hier Stunden dran arbeitest, dann ist es wichtig genug, dass sie sich fünf Minuten nehmen, um einen Abschnitt von drei Sätzen zu korrigieren.
• Unklarer Sinn? Irgendwann wird Dich jemand nach diesem Wissen fragen.

Damit bleiben Scope und die Halbwertszeit, quasi die Themen dieses Artikels. Eine gute Antwort auf beides ist automatische Datenerfassung. Ich habe doch versprochen, dass Faulheit siegt.

Das gewünschte Ergebnis bestimmt die Methoden

Ohne zu politisch zu werden: Computer loggen heutzutage fast alles mit, was wir mit ihnen tun. Wenn wir uns das zu Nutze machen, kann es extrem nützlich sein.

Es ist leicht, hier zu viele Daten zu sammeln. Wie die „Seven Habits of Highly Effective People“ uns lehren: „Begin with the end in mind.“ Wie genau sich Dokumentation gestaltet, kommt auf die Art der Tätigkeit an. Hier ein paar Beispiele:

• Security Audit / Penetration Test: Ich möchte mit Zeitstempel genau loggen, was ich wann mit welchem Tool mit welchem System gemacht habe. Am Ende möchte ich (1.) einen Bericht schreiben, der technisch kompetenten Personen erlaubt, meinen Angriff nachzumachen, Kommando für Kommando und (2.) dem Kunden helfen, alle von mir installierten Rootkits wieder loszuwerden und vielleicht auch (3.) zeigen, dass ich bestimmte Dinge nicht kaputt gemacht habe – also bestimmte Systeme gar nicht berührt habe.
• Systemadministration: Welche Einstellungen habe ich geändert und wann? Wie hat sich das Problem geäußert und welche Befehle waren nötig, um es zu lösen?
• Softwareentwicklung: Welche Entscheidungen habe ich hier getroffen und warum? Wie hat sich der Bug geäußert, welche Maßnahmen habe ich ergriffen, um ihn zu reparieren? Wie habe ich meine Dev-Umgebung zum Laufen bekommen und wie bin ich mit welcher Fehlermeldung umgegangen?

Der Computer soll mitschreiben

Wir erinnern uns an history und an export HISTTIMEFORMAT='%F %T'.

Unsere Shell zeichnet bereits mit, was wir so tun. Dieses Verfahren hat leider zwei gravierende Nachteile: Erstens hat jedes System seine eigene History. Wenn ich mich auf den Docker-Container verbinde, dann loggt der seine eigene History und meine Shell bekommt davon nichts mit. Zweitens sehe ich nur die Befehle, die ich eingebe – nicht den Output, den ich zurückbekomme. Glücklicherweise gibt es ein Tool dafür.

script ticket_BUG123.txt

Das wahrscheinlich ungooglebarste Tool der Welt ist Teil von util-linux und damit so Core, wie es eigentlich nur geht. Alles, alles, alles was jetzt in diesen Terminalprompt geschrieben oder gelesen wird, landet in dieser Datei; inklusive Backspaces. Es ist das perfekte Tool für einen persönlichen Auditlog oder eine Datengrundlage, um sicher zu gehen, dass man in den eigenen Notizen nichts vergisst.

Aber Vorsicht: auch Passwörter werden so mitgeloggt!

Raus geht es mit exit oder STRG+D.

script kann auch Zeitdaten mitschneiden … und abspielen.

script -t 2> timing.txt interessante_session.txt
# Dann die Session und wenn man fertig ist...
exit
scriptreplay timing.txt interessante_session.txt

Das ist eine schöne Überleitung zum nächsten Tool.

Kamera läuft!

Sei es eine Tool-Demo oder ein Bugreport, manchmal möchte man einfach eine Aufzeichnung einer Terminalsession teilen. Klassische Beispiel für Terminal-Gifs finden sich auf Asciinema.

Asciinema an sich bietet schon ein Tool dafür an, aber ich hadere meist damit – nicht zuletzt wegen etwaiger Vertraulichkeitserklärungen –, Daten auf Plattformen Dritter hochzuladen. Aber keine Sorge! Es gibt genug andere Tools die das können.

Der Klassiker (ttyrec) ist bei Arch Linux leider verwaist. Stattdessen verwende ich

termrec -f ttyrec recording_bash.log

… was exakt das Gleiche tut. Mit

ttygif recording_bash.log

kann ich mir dann ein hübsches Gif rausrendern, was Lesern dieses Adventskalenders vielleicht bekannt vorkommen könnte.

Derartige Gifs machen sich gut auf Websites oder in Slack-Channels, wo pastierter Output oder Screenshots einfach nicht reichen.

Das bringt mich zu …

Screenshots

Es ist kein Kommandozeilentool, aber ich mag flameshot.

Ultragerne. Es bringt alles mit, was ich von einem Screenshot-Tool haben will, sogar die Dinge, von denen ich nicht wusste, dass ich sie haben will. GPLv3 und bisher das reibungsloseste Tool, um schnell professionelle Screenshots zu erstellen.

Strukturiertes Ablegen

Manchmal ist Selbstdisziplin der faulste Weg nach vorne. Wir alle sind glaube ich vertraut mit dem Hirnfehler, dass wir zehn Minuten mit der Küchenschere an einer Verpackung rumprobieren, obwohl die Kombizange weniger als eine Minute entfernt im anderen Raum liegt.

Manchmal spart es sehr viel Zeit, einfach schnell das Richtige zu tun.

Eine gut sortierte Ablage ist der ultimative Faulheitshack. Ich habe bereits einen Blogpost über die Zettelkasten-Methode geschrieben. Ein Tool wie Obsidian (ich selber habe mir das Tooling inzwischen in vim hingefrickelt) kann hier echte Wunder wirken.

Die Idee sind Links. Ich habe eine Notiz für ein Ticket, in dem Links und Infos zu allem drin sind, was dieses Ticket betreffen. Eine rudimentäre (und unvollständige) Checkliste wäre:

• Jira-Link auf das Ticket
• relevante Confluence-Seiten
• relevante Miro-Boards
• Links auf Webseiten, die man sich bei der Bearbeitung ergooglet hat
• E-Mails (Permalinks, eigene Notiz oder direkt reinpasten)
• Slack-Nachrichten (Permalinks, eigene Notiz oder direkt reinpasten)
• Screenshots
• Logdateien
• Code-Schnippsel
• evtl. sogar Commit-Hashes
• eigene Notizen, Gedanken-Flow
• offene Fragen
• selbst-gemalte DOT-Diagramme (siehe meinen Adventskalender-Post zu diesem Thema)

Zur Erinnerung kann man sich hier leicht eine Vorlage bauen, die uns an alles erinnert.

Die Idee ist, dass wir in einem Ozean aus Daten schnell einen Korb flechten, in den wir alles relevante reinwerfen. Ordnung können wir schaffen, wenn uns irgendwer nochmal nach diesem Wissen fragt.

Der Zeitpunkt ist immer jetzt

Die Werkzeuge sind einfach: Plaintext-Dateien (oder Markdown) in einem Git-Repo.

Das Prinzip ist einfach: In dem Moment, in dem ich alles präsent habe, ist es am wenigsten Arbeit alles hier reinzuschreiben.

Wer wirklich die Selbstautomatisierung haben möchte, baut sich eine Checkliste zum Abarbeiten, die Teil der eigenen Definition of Done wird. Sind alle Browser-Tabs zu dem Thema zu? Sind alle relevanten Teile der History in der Notiz?

Es ist verblüffend, wie schnell diese Notizen nützlich werden. Ein einfaches

grep -ri "unknown error while opening file"

liefert den Kontext von vor Monaten, als besagter Fehler schon mal auftrat.

Freundschaft mit Datenkraken schließen

Die DSGVO macht es zu einer rechtlichen Vorgabe, dass wir alle Daten anfordern dürfen, die eine Firma über uns speichert. Bei manchen Firmen wie – sagen wir mal – Google können das ein paar mehr sein. Google stellt deswegen ein automatisches Tool zur Verfügung, über das wir ein Komplettarchiv all unserer Daten beziehen können. 

Googlesuchen? YouTube-Videos, die wir angeschaut haben? Chrome-History? Tausend Dinge, die wir auf unserem Android-Phone getan haben? All das liegt liebevoll sortiert in der Cloud. Das kann gruselig sein, aber auch nützlich!

„Ok, ich habe mich im Februar mit diesem Service beschäftigt. Und da habe ich irgendeinen nützlichen Vortrag gesehen. Wie hieß der nochmal ..?“

Commit-Messages und ADRs

Code-Kommentare werden schnell zu Lügen. Commit-Messages können leicht undurchsichtige Code-Entscheidungen erklären. Hier passt eine ganze Menge Text rein, der genau da auftaucht, wo er gebraucht wird. (git blame „Eric, warum hast Du hier … Oh. Ok.“)

Entscheidungen im Team sollten mit Architectural Decision Records nicht nur im Jira und/oder Wiki landen, sondern am besten gleich im Repo committet werden.

Hübsche Templates bedeutet schnelle Wissensvermittlung

Zurück zur Aufgabenstellung.

Im Ticket steht, dass das Projekt dokumentiert gehört.

Erste Rückfrage ist Zielgruppe und Ansatzpunkt. Punkt. Ohne die ist das Ticket nicht fertig spezifiziert. Eine README für Neue im Projekt? Eine API-Dokumentation für ein anderes Team? Eine Architekturskizze für Investoren?

Wenn es einfach nur eine Box-Ticking-Aufgabe ist („Wir brauchen halt Doku.“), dann nutzt es, um das eigene Projekt besser kennenzulernen und zu reflektieren.

Noch besser ist es, Wissen proaktiv nach außen zu tragen.

Mit Tools wie eisvogel kann ich Markdown-Dateien mit Copy-Paste in ein ansprechendes, professionell aussehendes PDF verwandeln.

pandoc bericht.md -o bericht.pdf --from markdown --template eisvogel --listings

Wichtig ist hier, die entsprechenden Attribute im Header zu setzen:

---
title: "Performance Bugs auf der Datenbankebene"
subtitle: "BUG321, BUG567, BUG901 und wie wir sie in Zukunft vermeiden"
author: Eric
date: "2023-11-21"
lang: "de"
---

Denselben Unterbau (pandoc und LaTeX) kann ich nutzen, um mir gleich Slides zu generieren.

pandoc -t beamer architektur.md -V theme:Warsaw -o architektur_präsentation.pdf

Wichtig ist hier ggf., den --slide-level anzupassen. Die Struktur der Folien orientiert sich an den Headern.

Ein wenig Arbeit in hübsche Templates zu stecken (oder sie sich vom Arbeitgeber abzuholen), kann das Erstellen solcher Dokumente erheblich erleichtern.

Wissensvermittlung hilft den Vermittelnden

Als ich noch etwas jünger war, habe ich von einem Senior gehört, der seine ganzen Notizen als Blogartikel veröffentlicht hatte. Jedes Mal wenn er was nicht mehr wusste, hat er seine eigenen Blogartikel durchsucht, um die Antwort zu finden. Damals erschien mir das bizarr. Würde man einen Blogartikel nicht über ein Thema schreiben, das man in- und auswendig kann? Warum würde man etwas mit dem man sich so gut auskennt wieder vergessen?

Heute weiß ich es besser. Nach 24 Blogartikeln für diesen Kalender alleine kann ich ein, zwei Weisheiten teilen.

Jeder Blogartikel ist eine Herausforderung. Ich mache mir immer noch neue Gedanken zum Thema, ich schaue immer noch Dinge nach, ich probiere Dinge aus und schaue in die Dokumentation.

Jeder Blogartikel ist eine Lernerfahrung. Aus jedem dieser Blogartikel habe ich neue Dinge gelernt – und sei es nur, dass ich meinen Kopf aufgeräumt habe.

Nur weil ich ein Thema jetzt präsent habe, heißt das nicht, dass ich es immer präsent haben werde. Seniors die krasse Vorträge halten, haben ihn vorher geübt. Haben sich auf Fragen vorbereitet. Haben vielleicht nochmal nachgeschaut, ob das, was in den Folien steht, noch aktuell ist.

Ich kann nicht empfehlen, 24 Blogartikel hintereinander in kurzer Zeit zu schreiben; aber ein paar davon im Monat sind sehr lohnenswert und nicht so schwierig, wie man vermuten möchte.