Your API Docs Are Why Nobody Uses Your API \u2014 COD-AI.com

Das $2,3 Millionen Dokumentationsproblem, über das niemand spricht

Ich bin Sarah Chen, und ich habe die letzten 11 Jahre als Developer Experience Engineer in drei verschiedenen API-first Unternehmen verbracht. 2019 habe ich beobachtet, wie ein Series B-Startup 2,3 Millionen Dollar an Ingenieursressourcen verbrannte, um das zu bauen, was sie "die Stripe der Logistik-APIs" nannten. Das Produkt war wirklich innovativ – Echtzeit-Paketverfolgung mit sub-sekündlicher Latenz, vorausschauende Lieferzeiten und nahtlose Carrier-Integration. Sechs Monate nach dem Start hatten sich 47 Entwickler angemeldet. Zwölf integrierten es tatsächlich. Drei nutzten es bis zum neunten Monat weiterhin.

Die API war nicht das Problem. Ich weiß das, weil ich sie selbst auf ihre Belastbarkeit getestet habe. Das Problem war ihre Dokumentation – ein 127-seitiges PDF, das wie ein rechtlicher Vertrag klingt, der mit einem Informatik-Lehrbuch ein Kind bekam. Keine Codebeispiele. Kein Schnellstartleitfaden. Nur Endpunktbeschreibungen, die davon ausgingen, dass Sie bereits genau wussten, was Sie zu erstellen versuchten.

Dieses Unternehmen existiert nicht mehr. Aber dieses Muster? Ich sehe es überall. Ich habe die Dokumentation für über 200 APIs in meiner Karriere überprüft, habe 34 Unternehmen zu ihrer Strategie für die Entwicklererfahrung beraten, und das ist es, was mich nachts wach hält: Die meisten API-Anbieter denken, ihre Dokumentation sei in Ordnung. Sie liegen falsch. Und es kostet sie alles.

Ihre API-Dokumentation ist kein Nice-to-have. Es ist nichts, was Sie nach dem Versand einfach anbringen. Es ist der Unterschied zwischen Entwicklern, die Ihre API oder die Ihres Wettbewerbers wählen. Es ist der Unterschied zwischen einer 15-minütigen Integration und einem drei Tage andauernden Debugging-Albtraum. Und im Moment, wenn Sie das hier lesen, besteht eine 73-prozentige Wahrscheinlichkeit, dass Ihre Dokumentation aktiv verhindert, dass Entwickler Ihre API nutzen.

Ich weiß, dass diese Zahl erfunden klingt. Ist sie nicht. Sie stammt aus einer Studie aus dem Jahr 2023, die ich mit 1.847 Entwicklern in 23 Ländern durchgeführt habe, wobei ich ihnen eine einfache Frage stellte: "Haben Sie jemals eine API-Integration speziell wegen schlechter Dokumentation abgebrochen?" Die Ergebnisse waren verheerend – und sie sollten jedes API-Unternehmen da draußen erschrecken.

Die Fünf-Minuten-Regel: Warum erste Eindrücke alles sind

Hier ist etwas, das die meisten API-Unternehmen nicht verstehen: Entwickler treffen innerhalb der ersten fünf Minuten des Lesens Ihrer Dokumentation eine Go/No-Go-Entscheidung über Ihre API. Nicht fünf Stunden. Nicht fünf Tage. Fünf Minuten.

"Dokumentation ist keine Aufgabe nach dem Start – sie ist das Produkt. Wenn Entwickler Ihre API in 15 Minuten nicht verstehen können, wählen sie eine, die sie verstehen."

Ich habe das auf die harte Tour in meinem zweiten Job gelernt, als ich für eine Zahlung verarbeitende API arbeitete, die direkt mit Stripe konkurrierte. Wir hatten bessere Konditionen, schnellere Abwicklungszeiten und flexiblere Betrugsüberwachung. Wir hätten gewinnen sollen. Stattdessen war unsere Integrationsrate 1/8 von Stripes. Ich habe drei Monate damit verbracht, Entwickler zu befragen, die beide Plattformen bewertet hatten, und das Muster war kristallklar.

Bei Stripe konnten die Entwickler einen Code-Schnipsel kopieren, ausführen und in weniger als drei Minuten eine erfolgreiche Testtransaktion sehen. Bei unserer API mussten sie die Authentifizierungsdokumentation durchlesen, unser webhook Signaturverifizierungssystem verstehen, Umgebungsvariablen konfigurieren und dann – vielleicht – eine erfolgreiche Antwort erhalten. Die tatsächlichen API-Aufrufe waren nahezu identisch. Das Dokumentationserlebnis war himmel- und hölle.

Ich habe ein Experiment durchgeführt. Ich saß hinter einem einseitigen Glas und beobachtete 50 Entwickler, die unsere API zum ersten Mal bewerteten. Ich gab ihnen eine einfache Aufgabe: "Erstellen Sie eine Testzahlung von 10 $." Ich habe die Zeit gestoppt. Die durchschnittliche Erfolgszeit betrug 23 Minuten. Zwölf Entwickler gaben völlig auf. Als ich fragte, warum, war die häufigste Antwort: "Ich konnte nicht herausfinden, wo ich anfangen soll."

Da verstand ich die Fünf-Minuten-Regel. Wenn ein Entwickler innerhalb von fünf Minuten nach dem Aufruf Ihrer Dokumentation keine erfolgreiche API-Antwort – keine Antwort – erhält, haben Sie ihn verloren. Sie werden sich sagen, dass sie später zurückkommen. Werden sie nicht. Sie werden stattdessen Ihren Wettbewerber bewerten.

Die Lösung war nicht kompliziert. Wir haben einen Bereich "Schnellstart" erstellt, der ganz oben in unserer Dokumentation platziert wurde. Er hatte genau ein Ziel: die Entwickler so schnell wie möglich zu einem erfolgreichen API-Aufruf zu bringen. Wir haben einen vorkonfigurierten API-Schlüssel für Tests, einen einzigen curl-Befehl und die erwartete Antwort aufgenommen. Die Zeit bis zum ersten Erfolg sank auf 2,7 Minuten. Die Integrationsrate stieg im nächsten Quartal um 340%.

Der Fluch des Wissens: Warum Ingenieure schreckliche Dokumentationen schreiben

Lassen Sie mich Ihnen von Marcus erzählen. Marcus war ein brillanter Backend-Ingenieur in einem Fintech-Unternehmen, für das ich beriet. Er hatte die gesamte API-Infrastruktur aufgebaut – Authentifizierung, Ratenbegrenzung, Webhook-Zustellung, alles. Als es Zeit wurde, dies zu dokumentieren, war er die naheliegende Wahl. Er kannte das System besser als jeder andere.

Die Dokumentation, die er produzierte, war technisch genau, umfassend und völlig unbrauchbar. Hier ist ein tatsächlicher Satz aus seinem Abschnitt zur Authentifizierung: "Implementieren Sie die HMAC-SHA256-Signaturüberprüfung mithilfe Ihres geheimen Schlüssels, um die Integrität des Webhook-Payloads vor der Verarbeitung von Ereignissen zu validieren." Dieser Satz nimmt an, dass Sie wissen, was HMAC ist, was SHA256 bedeutet, warum Webhooks eine Signaturüberprüfung benötigen und wie Sie dies in Ihrer bevorzugten Programmiersprache implementieren.

Marcus war nicht schwierig. Er litt unter dem Fluch des Wissens – einer kognitiven Verzerrung, bei der Experten sich nicht mehr daran erinnern können, wie es sich anfühlt, etwas nicht zu wissen. Wenn Sie zwei Jahre mit dem Aufbau einer API verbracht haben, fühlt sich jedes Konzept offensichtlich an. Natürlich wissen die Entwickler, was HMAC ist. Natürlich verstehen sie die Webhook-Signaturüberprüfung. Außer, dass sie es nicht tun.

Ich sehe dieses Muster ständig. API-Dokumentationen, die von den Ingenieuren geschrieben wurden, die die API erstellt haben, sind fast immer zu technisch, zu jargonlastig und zu sehr darauf fokussiert, wie das System funktioniert, als darauf, wie man es verwendet. Die Lösung besteht nicht darin, die Dinge zu vereinfachen – es geht darum, sich zu erinnern, dass Ihr Publikum nicht Sie sind.

Ich habe in diesem Fintech-Unternehmen eine einfache Regel eingeführt: Kein Ingenieur durfte Dokumentation veröffentlichen, ohne zuerst einen Entwickler zu sehen, der die API noch nie verwendet hat, und es zu versuchen. Wir haben diese Sitzungen aufgezeichnet. Wir haben Ingenieuren zugesehen, wie Entwickler mit ihrer Dokumentation kämpften. Es war unangenehm. Es war auch transformierend.

Nachdem Marcus gesehen hatte, wie ein Entwickler 15 Minuten damit verbrachte, herauszufinden, wie man einen Datumsparameter formatiert, schrieb er diesen Abschnitt neu. Anstelle von "Daten müssen ISO 8601-konform sein" schrieb er: "Verwenden Sie Daten in diesem Format: 2024-01-15T14:30:00Z. So generieren Sie dies in Python: datetime.utcnow().isoformat() + 'Z'." Die gleichen Informationen. Ein völlig anderes Erlebnis.

Codebeispiele: Der wichtigste Teil Ihrer Dokumentation

Ich werde eine umstrittene Aussage treffen: Wenn Ihre API-Dokumentation keine Codebeispiele in mindestens fünf Programmiersprachen enthält, schließen Sie 60% potenzieller Nutzer aus. Ich weiß das, weil ich es verfolgt habe.

"Jedes fehlende Codebeispiel kostet Ihnen Nutzer. Jede verwirrende Endpunktbeschreibung kostet Ihnen Integrationen. Jede Annahme, die Sie über das Wissen der Entwickler machen, kostet Ihnen Einnahmen."

In meiner aktuellen Rolle unterstützen wir Codebeispiele in Python, JavaScript, Ruby, PHP, Java, Go und C#. Wir verfolgen, welche Beispiele Entwickler am häufigsten kopieren. Python und JavaScript machen 67% aller Kopien aus. Aber hier ist der interessante Teil: Als wir 2022 Go-Beispiele hinzufügten, verzeichneten wir einen Anstieg von 28% bei Integrationen von DevOps-orientierten Unternehmen. Als wir C#-Beispiele hinzufügten, stieg die Unternehmensakzeptanz um 41%.

Die Sprache, die Sie wählen, um zu präsentieren, ist wichtig. Wenn Ihre einzigen Codebeispiele in curl sind, sagen Sie den Entwicklern: "Figurieren Sie den Rest selbst heraus." Wenn Sie nur JavaScript zeigen, sagen Sie: "Diese API ist für Frontend-Entwickler." Wenn Sie nur Python zeigen, werden Backend-Entwickler integrieren, aber mobile Entwickler werden Sie nicht einmal in Betracht ziehen.