Salzkammercode entwickelt Software, deren Herzstück eine API ist – die Schnittstelle, über die Kundensysteme mit der Anwendung reden. Die API ist über Jahre gewachsen. Die Dokumentation ist leider nur stellenweise mitgewachsen: Neue Entwickler brauchten Tage, um die erste Anfrage zum Laufen zu bringen, und im Support landeten Fragen, die eigentlich eine Doku beantworten sollte.
Gemeinsam mit dem Entwicklerteam habe ich die API-Dokumentation von Grund auf neu aufgebaut:
- Bestandsaufnahme: Was ist dokumentiert, was stimmt noch, was fehlt ganz?
- Neue Struktur: Erste Schritte, Anwendungsfälle und Referenz sauber getrennt
- Einheitliche Terminologie für Endpunkte, Parameter und Fehlermeldungen
- Praxisnahe Codebeispiele für die häufigsten Anwendungsfälle
Das Wichtigste dabei: Die Doku entsteht nicht neben der Entwicklung, sondern mit ihr. Sie lebt im selben Repository wie der Code und wird bei jedem Release mitgeprüft. So bleibt sie aktuell – statt in einem PDF zu altern, das niemand mehr öffnet.
Der spannendste Teil der Arbeit war das Zuhören: Ich habe mich zu den Entwicklern gesetzt und sie die ersten Schritte mit ihrer eigenen API erklären lassen. Dabei zeigt sich schnell, wo Wissen implizit ist – die Stellen, an denen ein erfahrener Entwickler sagt: „Das muss man halt wissen.“ Genau diese Sätze sind Gold wert: Aus jedem davon wurde ein Kapitel der neuen Dokumentation.
Eine API ist nur so gut wie ihre Dokumentation: Was Entwickler nicht finden, benutzen sie nicht – oder falsch.
Das Ergebnis kann sich sehen lassen: Der Weg vom Zugang bis zur ersten erfolgreichen Anfrage dauert heute Minuten statt Tage. Die Support-Anfragen zur API sind spürbar zurückgegangen, und neue Teammitglieder arbeiten sich selbstständig ein. Und das Schönste für mich als Textmonteurin: Die Entwickler pflegen die Doku inzwischen freiwillig weiter – weil sie ihnen selbst hilft.
Du hast auch eine API oder eine andere Schnittstelle, die mehr kann, als ihre Doku verrät? Dann melde dich – ich bringe das für dich in Form.
