Eine Seite kann Jahre alt und trotzdem korrekt sein
Dokumentation wird still überholt und nach Datum geprüft, das markiert die Seiten, die niemand ändern musste, und verfehlt die Seite, die letzten Dienstag falsch wurde.
Alter ist ein schlechter Stellvertreter. Eine vor zwei Jahren geschriebene Konzeptseite kann vollkommen zutreffend sein, während ein letzten Monat bearbeiteter Quickstart falsch sein kann, weil sich ein Default darunter geändert hat.
Falschheit ist eine Beziehung zwischen zwei Dingen: was der Code jetzt tut und was die Seite sagt, dass er tut. Das zu prüfen, heißt, beides zu lesen. Das Lesen ist eng: Parameternamen, Defaults, Rückgabeformen und geforderte Reihenfolge.
Mit zitiertem Widerspruch zu markieren, macht das nutzbar. Eine Liste möglicherweise überholter Seiten wird ignoriert. Eine Liste, die sagt, diese Zeile sagt X und der Code tut jetzt Y, wird behoben.
So läuft der ActionFlow auf der Canvas
Zwei Eingaben speisen den Flow. Ein GitHub-Knoten liefert die seit der letzten Prüfung gemergten Änderungen. Ein Notion- oder HTTP Request-Knoten liefert die veröffentlichten Dokumentationsseiten.
Ein Filter-Knoten verengt die Änderungen auf die, die eine öffentliche Oberfläche berühren (Signaturen, Defaults, Konfiguration, öffentliche Typen), weil ein internes Refactoring eine Seite nicht falsch machen kann.
Ein Loop-Knoten geht die restlichen Änderungen durch. Zu jeder gibt ein Generate Object-Knoten die Dokumentationspassagen zurück, die das geänderte Verhalten beschreiben, zitiert.
Ein zweiter Generate Object-Durchgang beurteilt jede Passage gegen die Änderung und gibt einen von drei Zuständen zurück: widersprochen mit dem Zitat, unvollständig oder unberührt.
Die dreistufige Antwort hält die Ausgabe kurz. Die meisten Passagen kommen unberührt zurück und erreichen niemanden.
Ein Filter-Knoten behält die widersprochenen und unvollständigen Funde. Ein Sort-Knoten setzt Widersprüche zuerst, weil das die sind, die Leserinnen und Leser aktiv in die Irre führen.
Ein GitHub-Knoten öffnet ein Issue je betroffener Seite, mit Zitat und Änderung. Ein Slack-Knoten postet die Zahl in den Dokumentationskanal.
Der Flow bearbeitet keine Seite. Die Korrektur macht ein Mensch, mit dem Widerspruch vor sich.
Knoten, die dieser ActionFlow verwendet
- GitHub (Integration): die seit der letzten Prüfung gemergten Änderungen.
- Notion (Integration) with HTTP Request (Util): die Dokumentationsseiten so, wie veröffentlicht.
- Filter (Data): verengt auf Änderungen, die eine öffentliche Oberfläche berühren.
- Loop (Control): ein Durchgang je Änderung, nicht ein Durchgang über alles.
- Generate Object (AI Core): die Passagen, die das geänderte Verhalten beschreiben, zitiert.
- Generate Object (AI Core): widersprochen, unvollständig oder unberührt, je Passage.
- Sort (Data): Widersprüche zuerst.
- GitHub (Integration): ein Issue je betroffener Seite, mit Zitat und Änderung.
Häufige Fragen
Newsletter
Produktupdates erhalten
Neue Nodes, Agents und Produktnotizen. Wir senden E-Mails nur, wenn sich das Öffnen lohnt.