API-Dokumentation in Excel oder PDF zu erstellen und per E-Mail zu teilen, ist uns allzu vertraut.
Wenn ein Problem auftritt, kontaktiert man die zuständige Person und durchsucht alte E-Mails, um zu prüfen, welche Version der Dokumentation der Kunde hat. Man erklärt die Änderungen erneut, sendet die überarbeitete Dokumentation und prüft anschließend noch einmal, ob alles korrekt übernommen wurde.
Wir haben diesen Prozess so oft wiederholt, dass wir angefangen haben zu glauben, er gehöre eigentlich zur notwendigen Arbeit.
Aber das Problem endet nicht bei einem einzigen fehlerhaften Dokument.
Jedes Mal, wenn sich die API ändert, kommen neue Dateien und E-Mails, kundenspezifische Ausnahmen und die Erinnerungen der zuständigen Personen hinzu. Anfangs ist es nur eine kleine Unannehmlichkeit, doch mit der Zeit wird es immer schwieriger zu erkennen, welches Dokument maßgeblich ist, und auch die Menschen und die Zeit, die zur Lösung von Problemen nötig sind, nehmen zu.
Wenn ein Kunde auf Basis eines Anfrageformats einer älteren Version entwickelt, entstehen Integrationsfehler und Nacharbeiten. Werden Pflichtfelder oder Authentifizierungsmethoden anders vermittelt, verzögert sich der Entwicklungszeitplan, und wenn die API bereits produktiv läuft, kann das sogar zu Datenfehlern oder Ausfällen führen.
Erst nachdem ein Problem aufgetreten ist, stellt man fest, dass das interne Entwicklungsteam und der Kunde unterschiedliche Dokumente angesehen haben.
Ab diesem Moment stoppt der Entwickler seine laufende Arbeit und sucht nach der Ursache. Das Operations-Team sucht alte Dokumente und Übermittlungsverläufe heraus, und der Kunde überprüft erneut seine Implementierung und die erhaltene Spezifikation. Eine einzige Abweichung in einem Dokument kann die Arbeit mehrerer Personen gleichzeitig zum Stillstand bringen.
Trotzdem werden die meisten Probleme still per Telefon, E-Mail oder Messenger gelöst.
Jemand versendet die korrigierte Datei erneut, jemand erklärt dem Kunden die Situation, und der Entwickler fügt hastig eine Ausnahmebehandlung hinzu. Das unmittelbare Problem ist damit gelöst, aber warum es entstanden ist, welche Kunden betroffen waren und was geändert wurde, damit sich derselbe Fehler nicht wiederholt, bleibt in der Organisation nicht erhalten.
Die Zeit, die in diesen Prozess fließt, hätte ursprünglich für Entwicklung und Produktverbesserung genutzt werden sollen.
Das größere Problem ist, dass dieser gesamte Ablauf von der Erfahrung, der Erinnerung und dem E-Mail-Postfach einer bestimmten zuständigen Person abhängt. Wenn diese Person abwesend ist oder das Unternehmen verlässt, muss die Organisation E-Mails und Messenger-Verläufe durchforsten, um den Ablauf wiederherzustellen.
Unverwaltete API-Dokumentation verschwindet nicht. Sie bleibt innerhalb und außerhalb der Organisation bestehen und wird zu unsichtbarer Dokumentationsschuld.
Vielleicht lösen wir das Problem also gar nicht, sondern haben uns nur daran gewöhnt, es jedes Mal mit der Zeit von Menschen abzufangen, wenn es auftritt.
Weil ich diese Probleme in der Praxis selbst erlebt habe, habe ich SpecBridge entwickelt.
SpecBridge ist nicht einfach nur ein Tool zum Schreiben von API-Dokumentation. Es ist ein Tool für den Betrieb von API-Dokumentation, mit dem Änderungen geprüft und nur freigegebene Versionen an Kunden und externe Partner verteilt werden.
Es ersetzt bestehendes Swagger nicht, sondern konzentriert sich darauf, Swagger/OpenAPI und Postman Collection zu importieren und anschließend die Probleme zu verwalten, die bei der Weitergabe nach außen entstehen.
- Vergleich der Unterschiede zwischen aktueller veröffentlichter Version und überarbeiteter Version
- Prüfung und Freigabe von Änderungen
- Trennung zwischen Entwurf und der veröffentlichten Version, die der Kunde sieht
- Verwaltung des Sichtbarkeitsumfangs der Dokumentation pro Kunde
- Festlegen von Passwort und Ablaufdatum für öffentliche Links
- Bereitstellung der neuesten freigegebenen Dokumentation unter demselben Link
Anstatt dem Kunden jedes Mal neue Dateien zu schicken, kann nach Abschluss der internen Prüfung nur die Dokumentation erneut unter dem bestehenden Link veröffentlicht werden.
Entwickler können die wiederkehrende Arbeit des Suchens und erneuten Versendens von Dokumentation reduzieren, und die Organisation kann API-Dokumentation nicht anhand der Erinnerung einer bestimmten zuständigen Person, sondern auf Basis protokollierter Änderungshistorien und Veröffentlichungsstandards verwalten.
Derzeit suche ich Partner, die SpecBridge im echten Betrieb von API-Dokumentation einsetzen und ehrliches Feedback geben.
Wenn Ihr Team API-Dokumentation mit Excel oder PDF verwaltet oder bei jeder API-Änderung Dokumentation erneut an Kunden verschickt, würde ich gern gemeinsam schon mit einem einzigen derzeit verwendeten Dokument prüfen, wie sich das verbessern lässt.
Mehr als Lob für gut gebaute Funktionen möchte ich ehrliche Meinungen zu unbequemen Punkten im realen Betrieb, unnötigen Abläufen und fehlenden Funktionen hören.
Noch keine Kommentare.