Code, Dokumentation und Veröffentlichung mit Notion
Wenn ich an einer neuen Softwarekomponente arbeite, schreibe ich mir relativ früh auf, was ich da eigentlich tue. Ich versuche dabei direkt zusammenhängenden Text zu schreiben, nicht in Stichpunkten, damit ich auch später wieder schlau daraus werde. Im Grunde eine Dokumentation für mich selbst. Was ist das hier für ein Baustein, wie fügt er sich ins Gesamtsystem ein, welche Entscheidungen habe ich unterwegs getroffen und warum. Vor allem aber: Was muss ich wissen, wenn ich in ein paar Monaten wieder an dieser Stelle lande und mich erst einmal orientieren muss.
Diese Texte entstehen ganz normal in Notion, so wie man auch in einer klassischen Textverarbeitung schreiben würde. Für mich ist das vor allem deshalb praktisch, weil ich dort sehr unterschiedliche Inhalte an einem Ort zusammenbringen kann. Ich kann erklärenden Text schreiben, Code einfügen und dabei Syntax-Highlighting nutzen, Bilder ergänzen oder Zusammenhänge visuell festhalten. Das Dokument ist dadurch nicht auf reinen Text beschränkt, sondern passt sich dem an, was gerade erklärt werden soll.
Gleichzeitig denke ich beim Schreiben schon darüber nach, wofür dieser Text später genutzt wird. Ob er nur mir selbst beim Wieder-Einsteigen helfen soll oder ob er auch von außen gelesen wird. Ob es eher eine interne Dokumentation ist oder bereits eine Anleitung, mit der andere konkret arbeiten sollen. Diese Einordnung passiert nicht am Ende, sondern begleitet das Schreiben von Anfang an.
Ein weiterer Vorteil: Ich kann die Dokumentation direkt mit dem Quellcode verknüpfen. In Notion kann ich Links zu Seiten oder Inhaltsblöcken kopieren. Diese Links füge ich im Quelltext an den entsprechenden Stellen als Kommentar ein. Immer dann, wenn an einer Stelle mehr Kontext nötig ist oder eine Entscheidung erklärt werden sollte, verweist der Code direkt auf die entsprechende Dokumentationsstelle. Wer später im Quelltext liest, kann mit einem Klick nachschauen, was damals der Gedanke dahinter war.
Der technische Teil kommt erst danach ins Spiel. Auch wenn ich den Text nicht bewusst in Markdown schreibe, verwaltet Notion die Inhalte intern genau so. Spätestens dann, wenn man sie kopiert, exportiert oder automatisiert weiterverarbeitet, liegt der Text als Markdown vor. Das ist der Übergangspunkt zwischen der Arbeitsdokumentation und allem, was daraus weiter entsteht.
Wenn eine Dokumentation einen Stand erreicht hat, bei dem sie nicht mehr nur mir selbst hilft, sondern auch für andere gedacht ist, ändert sich am Text erst einmal nichts. Der Unterschied liegt im Einsatz. Schreibe ich parallel zur Entwicklung eine Anleitung für einen Kunden oder für ein Produkt, mit dem andere Menschen arbeiten sollen, dann ist genau dieser Text die Grundlage. Er wird als Markdown auf den entsprechenden Server kopiert und dort veröffentlicht – zum Beispiel als Anleitung auf einer Homepage. Es entsteht kein neuer Text für „außen“. Die Dokumentation bzw. Anleitung, die mir beim Entwickeln hilft, ist dieselbe, die später jemand liest, der das System nutzt.
Ob dieser Schritt manuell passiert oder automatisiert, etwa über n8n, ist eher eine praktische Entscheidung. Manchmal ist es schneller, eine Datei einfach rüberzuschieben. Manchmal ist es angenehmer, wenn es automatisch läuft. Entscheidend ist nur, dass der Text nicht doppelt gepflegt wird.
Ich habe mir dafür ein kleines Skript gebaut, das Markdown-Dateien in HTML umwandelt, damit sie sich sauber in einer Webseite darstellen lassen. Dieses Skript liegt zentral auf unserem Server und wird von unterschiedlichen Webseiten genutzt, auf denen Dokumentationen oder Anleitungen angezeigt werden sollen. Auf der jeweiligen Zielseite selbst passiert dann nicht mehr viel. Es wird ein Platzhalter eingebunden, das Skript geladen, und genau an dieser Stelle erscheint der Inhalt. Der Text kommt aus der Markdown-Datei, die Darstellung übernimmt das Skript mit etwas CSS.
Der eigentliche Ablauf ist dabei ziemlich einfach. Die während der Programmierung entstandene Dokumentation gehe ich vor der Veröffentlichung noch einmal bewusst durch. Nicht, um sie neu zu schreiben, sondern um sie abzurunden und zu vervollständigen. In der Entwicklung ändern sich Dinge, manches wird angepasst, anderes vergisst man im Eifer des Gefechts zu dokumentieren. Formulierungen werden klarer, Stellen ergänzt, die für andere wichtig sind. Die Veröffentlichung ist kein eigener Dokumentationsmarathon, sondern eher ein letzter Feinschliff.
Ein weiterer Punkt, der sich über die Zeit als sehr hilfreich erwiesen hat, ist die Wiederverwendung von Inhalten. In Notion lassen sich Blöcke synchronisieren, sodass bestimmte Abschnitte an mehreren Stellen eingebaut werden können. Gerade grundlegende Erklärungen oder wiederkehrende Hinweise tauchen in mehreren Dokumentationen oder Anleitungen auf. Anstatt sie immer wieder leicht anders zu formulieren, gibt es sie einmal, und sie werden dort verwendet, wo sie gebraucht werden. Wenn sich etwas ändert, wird es an einer Stelle angepasst.
Am Ende geht es mir dabei vor allem darum, mir selbst das Arbeiten einfacher zu machen. Weniger Dinge im Kopf behalten zu müssen, schneller wieder ins Thema zu kommen und Entscheidungen nicht jedes Mal neu erklären zu müssen. Mich würde interessieren, ob andere Entwickler ähnlich arbeiten oder ganz andere Wege gefunden haben, mit Dokumentation im Alltag umzugehen.
