Die meisten Entwickler:innen sind nicht gerade scharf auf Dokumentation. Und wie so oft: Uns nervt etwas? Wir automatisieren es! (Und erhöhen sogar noch die Qualität der Ergebnisse.)
Warum Dokumentation für Make-Szenarien wichtig (nein: essentiell) ist
Wenn du Szenarien an Kunden oder andere Entwickler weitergibst, reicht die Darstellung in Make nicht immer aus. Klar, die Szenarien sind unter Umständen schon gut lesbar, manche Feinheiten verstecken sich in Variablen, Inputs oder im Ablauf. Insbesondere bei größeren Use-Cases oder dem Einsatz von Subszenarien wird es dann mal schnell komplizierter, das alles nachzuvollziehen.
Wir haben dsa automatisiert und das Ergebnis ist ein klar strukturiertes Dokument. Es liefert Kontext, Eingaben, Ausgaben und ein schematisches Modell des Ablaufs. Übergaben? Schnell! Rückfragen? Hoffentlich keine!
Die automatisierte Lösung zur Doku
Sven hat ein Szenario gebaut, das aus wenigen Bausteinen eine vollständige Dokumentation erzeugt. Es liest Daten aus einer Airtable-Zeile, nimmt ein Blueprint-Dokument, formatiert Inhalte als Markdown und erstellt zusätzlich Mermaid-Code für Flowchart und Sequenzdiagramm. Anschließend generiert das Szenario ein GoogleDoc mit allen Elementen und hinterlegt den GDrive-Link in Airtable.
Technische Umsetzung
So arbeitet das Szenario:
- Webhook empfängt Record-ID aus Airtable und ruft die entsprechende Zeile ab.
- Blueprint-Dokument wird geladen und per Prompt in lesbares Markdown umgewandelt.
- Ein zweiter Prompt erzeugt Mermaid-Code für Flowchart und Sequenzdiagramm.
- Aus der Analyse entsteht ein JSON, das die Diagramme und die Dokumentstruktur enthält.
- Google Doc wird erstellt; Beschreibung, Inputs, Outputs, Bemerkungen und Platzhalter für Bilder werden eingefügt.
- Mermaid-Code wird an einen Rendering-Service (z. B. Mermaid.ink/svg) geschickt, um ein SVG/PNG zu erhalten.
- Optional: Diagramm-Base64 wird in Cloudinary oder einen anderen Asset-Host hochgeladen.
- Abschluss: Link zum fertigen Dokument wird in Airtable eingetragen.
Tipps zur zuverlässigen Erstellung der Diagramme
Die Diagramm-Erzeugung ist der kniffligste Teil. Leider liefert nicht immer einen „erfolgreichen“ 200-Status. Manchmal bekommst du 400er oder 404er und der Upload schlägt fehl. Entscheidend ist deshalb die Fall-Back-Strategie mit dem Error Handler bei Cloudinary. Du kannst dann anschließend den Mermaid-Code manuell im Mermaid-Editor rendern. Das ist zwar etwas unpraktisch, funktioniert aber zuverlässig und ist schnell.
Exkurs: Könnten wir das mit einem AI Agent verbessern?
Beim Arbeiten mit diesem Szenario ist mir aufgefallen, dass dies ein sinnvoller Einsatz für einen KI Agenten sein könnte (wir bauen hier vermutlich auch weiter).
Entscheidend für die Lesbarkeit, Wartbarkeit und Robustheit von Automatisierungen sind auch die entsprechenden Konventionen, die eingehalten werden. Das beginnt mit etwas einfachem wie einem Namen (Szenario und Module) und endet mit Validierungen und Error-Handling.
Ein entsprechender Agent könnte dann einserseits die Qualität des Szenarios prüfen und erst, wenn die entsprechenden Basics eingehalten werden, an den Dokumentierer weiterreichen.
Oh und noch etwas: theoretisch ist der Zwischenschritt mit Airtable nicht notwendig. Du könntest auch direkt mit der Make-API und „get blueprint“ die Blueprints verarbeiten. Aber übersichtlicher finden wir es in der Airtable!
Doku einfach an eine Automatisierung delegieren.
Gleich loslegen? Aufsetzen kannst du die diese intelligente Prozessautomatisierung in drei Phasen:
- Datenaufnahme mit Airtable aufsetzen und in make einbinden: Webhook → Airtable Get Record → Blueprint-Download.
- Verarbeitung: Prompt für Markdown → Prompt für Mermaid → JSON erzeugen.
- Ausgabe: Google Doc erstellen → Diagramme rendern (automatisch mit Retry oder manuell) → Links zurückschreiben.
Die beschriebene Lösung liefert dir eine reproduzierbare Dokumentation mit Text und Diagrammen. Und erweiterbar ist das ganze natürlich auch, beispielsweise mti der Agent-Idee!
Viel Erfolg beim Nachbauen.
Das Video zur Auto-Doku von make-Szenarien mit make.com
Die komplette Anleitung zum Nachbauen: Das komplette Video von Sven findest auf YouTube!
