Lesedauer: 9 Minuten
APIs bringen die Welt in Schwung. Entwickler verwenden APIs fast jeden Tag – Schätzungen zufolge verbringen sie wöchentlich mehr als 10 Stunden mit APIs. Dabei geht es nicht nur darum, sie zu nutzen, sondern auch darum, zu recherchieren, nach Support zu googeln, Bewertungen zu lesen und natürlich in der Dokumentation zu stöbern. Wie klar, einfach, nützlich und unterstützt Ihre API ist, bestimmt die gesamte Entwicklererfahrung (DX) – eine emotionale Reaktion der Entwickler auf das Produkt. In der API-Wirtschaft ist eine großartige Entwicklererfahrung von grundlegender Bedeutung. APIs, die Entwicklern helfen, erfolgreich zu sein, und deren Nutzung Spaß macht, werden viele Nutzer finden und sich von der Konkurrenz abheben. Und das beginnt genau in dem Moment, in dem sie die Dokumentation zum ersten Mal öffnen.
Schauen Sie sich dieses Video an, um eine Einführung in die API-Technologie zu erhalten
Heute werden wir darüber sprechen, wie man eine positive Entwicklererfahrung in der API-Dokumentation fördern kann. Aber zuerst müssen wir verstehen, was schlechte API-Dokumente ausmacht.
Was Entwickler in der API-Dokumentation hassen
Die Entwicklergemeinschaft ist eine leidenschaftliche Gemeinschaft. Sie ist besonders leidenschaftlich, wenn es um Dinge geht, die sie nicht mögen. Wenn sie eine API nicht mögen, dann liegt das meistens an den miserablen Dokumentationen, selbst wenn das Produkt eigentlich großartig ist. Hier sind einige häufige Probleme, die Entwickler mit API-Dokumenten haben.
Sie sind nicht in einfacher menschlicher Sprache geschrieben. Dies ist ein häufiges Problem bei automatisch generierten oder von den Erstellern vernachlässigten Dokumenten. Obwohl viele Tools zur Dokumentationserstellung den Code sehr gut kommentieren, können sie tatsächliche Erklärungen in englischer Sprache, die von einem Entwickler oder technischen Redakteur verfasst wurden, nicht ersetzen.
Sie enthält sehr wenige Codebeispiele. Dies ist ein weiteres Ende des Spektrums, bei dem Erklärungen reichlich vorhanden sind, aber es gibt nur wenige Beispiele für den tatsächlichen Code.
Sie ist nur für registrierte Benutzer verfügbar. Dieses nicht sehr geschickte Manöver ist nicht gut für Ihr Marketing. Es frustriert nur die Leute, die wissen wollen, was Ihre API kann, bevor sie sich entscheiden, ob sie sie haben wollen (wie es jeder vernünftige Mensch tun würde).
Sie ist zu lang/unauffindbar/ungenau/ist seit Jahren nicht mehr aktualisiert worden usw. Die Erstellung einer guten Dokumentation ist fast so wichtig wie die Entwicklung einer guten API. Denn schlecht geschriebene Dokumentationen oder solche, die nicht gefunden werden können, wenn man einfach nach „Produkt-API“ googelt, scheitern an der gesamten Entwicklungsarbeit. Falls es Sie interessiert, haben wir bereits die Besonderheiten der technischen Dokumentation im Allgemeinen beschrieben. Aber API-Dokumente verdienen einen eigenen Artikel. Wie schreibt man also gute API-Dokumente?
Spec-driven Development
Spec-driven Development (SDD) ähnelt der testgetriebenen Entwicklung, bei der man für jede Funktion Testfälle schreibt und dann den Code, der sie bestehen soll. Bei der SDD erstellen Sie parallel zur Erstellung einer API die Dokumentation oder zumindest Teile davon, wobei Sie oft einem bestimmten API-Beschreibungsformat folgen, das als Spezifikation bezeichnet wird.
Eine API-Spezifikation ist wie eine Vorlage für Ihre künftige Dokumentation, die einheitliche Sprache, die das Design Ihrer API beschreibt, erklärt, wie sie funktioniert und was man von ihr erwarten kann. Es gibt einige Spezifikationen wie RAML (RESTful API Modeling Language), OpenAPI (früher Swagger) und API Blueprint, aber es gibt einen Trend, alle Spezifikationen unter der Haube von OpenAPI zu vereinen.
Diese Spezifikationen haben vorgefertigte Dokumentationswerkzeuge, die das Schreiben und Verwalten Ihrer Dokumente ermöglichen. API Console zum Beispiel generiert automatisch Dokumente aus RAML- und OpenAPI-Formaten und hilft Ihnen dabei, sie in Ihrer bestehenden Webanwendung oder als eigenständige Anwendung auszuführen.
API Console lässt Sie ein Webportal für Ihre API-Dokumente aus RAML- und OpenAPI-Spezifikationen erstellen
Quelle: Pawel Psztyc
Alternativ zu herkömmlichen API-Dokumentenlösungen wie WordPress oder Drupal CMS sind API-Spezifikationsprodukte quelloffen, werden von der Entwicklergemeinschaft für die Entwicklergemeinschaft erstellt, verfügen über Parser in verschiedenen Programmiersprachen und bieten ständigen Support für die Ersteller.
Schreiben Sie für Einsteiger
Es gibt einen Grund dafür, dass technische Dokumentationen in der Regel nicht von den Entwicklern selbst geschrieben werden – das ist die Aufgabe von technischen Redakteuren, die Experten darin sind, technische Aspekte in ein lesbares Format zu übersetzen. Aber selbst technische Redakteure neigen dazu, ein wenig Fachjargon in den Text einfließen zu lassen.
Eine API wird wie jedes Softwareprodukt für eine bestimmte Zielgruppe erstellt. Aber die Zielgruppe für die Dokumentation ist riesig. Es gibt drei Hauptgruppen von Dokumentationsbenutzern:
- Entwickler, die sich intensiv mit der Dokumentation auseinandersetzen werden
- Entscheidungsträger wie CTOs und Lösungsarchitekten, die schnell feststellen wollen, ob Ihre API eine gute Lösung ist
- Beobachter wie Journalisten, technische Redakteure und sogar Konkurrenten, die Ihre API nicht unbedingt jemals benutzen werden.
Und selbst innerhalb jeder dieser Gruppen gibt es Menschen mit unterschiedlichen Fähigkeiten, Rollen und Bedürfnissen, die alle eine positive Erfahrung mit den Dokumenten machen sollten. Wie kann man sie alle ansprechen? Indem man sich an die am wenigsten erfahrenen Benutzer wendet. Wie schreibt man also Dokumentationen für Neulinge?
Beginnen Sie mit den Möglichkeiten und nicht mit den technischen Einzelheiten. Begrüßen Sie die Benutzer mit einer fesselnden Geschichte, die zeigt, wie Ihre API ihr Produkt bereichern oder das Leben von Entwicklern zehnmal einfacher machen kann.
Amazon Alexa API-Dokumente beginnen mit der Erklärung, was Alexa tut und welchen Nutzen es dem Kunden bringen kann
Zeigen Sie, wo man anfangen soll. API-Dokumente sind berüchtigt dafür, dass sie zu überwältigend sind und davon ausgehen, dass die Benutzer über große Erfahrung mit APIs verfügen. Der Abschnitt „Erste Schritte“ ist obligatorisch, und er sollte mit Geduld für einen potenziellen Benutzer geschrieben werden.
Facebook bietet eine klare Referenz für Anfänger und folgt dem Prozess der ersten Schritte Schritt für Schritt
Erstellen Sie Anleitungen für die häufigsten Anwendungsfälle. Sie wissen wahrscheinlich bereits, für welche Funktionen Ihre API verwendet wird. Erstellen Sie separate Abschnitte, die sich mit diesen Funktionen befassen, und fügen Sie dort Beispielnachrichten ein.
Verwenden Sie einen lockeren Ton. Die Entwicklergemeinde ist locker und ungezwungen, daher wird sie trockene Unternehmenssprache nicht zu schätzen wissen, auch wenn sie „professioneller“ klingt. Gute Dokumentationen sprechen immer mit Menschen.
Schulen Sie externe Tools. Wenn Ihre API die Verwendung und das Verständnis von Produkten und Konzepten von Drittanbietern wie OAuth oder npm erfordert, fügen Sie Links zu Dokumenten oder Installationsanleitungen ein.
Machen Sie es einfach zu lernen. API-Dokumente sind keine IKEA-Montageanleitungen; sie sind die Lernquelle. Reichern Sie Ihre Dokumentation mit FAQs, Tutorials, Blogs und sogar Videos an, wenn möglich.
Integrieren Sie „Must-have“-Abschnitte
Im Jahr 2019 hat SmartBear, der Entwickler von Swagger, API-Entwickler und -Nutzer befragt. Sie fanden heraus, welche Dokumentationsfunktionen in der Community als am wichtigsten angesehen werden, und gaben uns eine Liste der „Must-Have“-Dokumentationsabschnitte, die Entwickler abdecken wollen. Wir werden einige davon durchgehen.
SmartBear befragte 3.000 API-Praktiker
Beispiele. Beispiele werden in der Regel als Codestücke präsentiert, die zwar nützlich genug sind, aber noch praktischer gestaltet werden können. Zum Beispiel, indem man eine Abschrift von Feldern einfügt, wie es in den Medium-Dokumenten gemacht wird, oder indem man eine Mock-API erstellt, die Entwickler testen und verwenden können, indem sie echte Aufrufe machen. Mock-APIs können einfach über eine URL oder auf GitHub geteilt werden, und wenn sie ein gewisses Maß an Detailgenauigkeit aufweisen, können sie sogar im Endprodukt verwendet werden.
Status und Fehler. Es gibt Standard-Statuscodes und solche, die spezifisch für Ihre API sind. Es ist eine gute Idee, alle Fehler, die durch Ihre API ausgelöst werden können, anzugeben. Fehler werden oft auf einer eigenen Seite der Dokumentation aufgeführt, aber es ist sinnvoll, einige von ihnen direkt unter dem Endpunkt zu duplizieren, wo sie am häufigsten auftreten.
Authentifizierung. Die meisten API-Dokumente beginnen mit der Authentifizierung und Autorisierung. Es sollte Informationen darüber enthalten, wie man einen API-Schlüssel erhält und wie man Anfragen authentifiziert, einschließlich möglicher Fehler, Token-Ablaufzeiten und einer Erklärung zur Authentifizierungssensitivität (im Grunde eine Erinnerung daran, dass Schlüssel nicht weitergegeben werden können und wo sie verwendet werden können).
HTTP-Anfragen. Die Bereitstellung von Web-Anfragen in HTTP ist das absolute Minimum für die Dokumentation. Normalerweise wird davon ausgegangen, dass Entwickler wissen, wie man HTTP-Anfragen in der Sprache ihrer Wahl sendet, aber manchmal fügen API-Ersteller Anfragen in verschiedenen Sprachen hinzu. Dies kann automatisch über API-Spezifikations- und API-Verwaltungstools wie Postman erfolgen.
Verwenden Sie ein Layout nach Industriestandard
Wenn Sie einen Dokumentationsgenerator verwenden, ist das Layout bereits für Sie festgelegt. Die meisten API-Dokumente sehen gleich aus und fühlen sich gleich an. Wenn Sie schon einige benutzt haben, wissen Sie, wie Sie an neue Dokumentationen herangehen müssen. Dennoch ist es eine komplexe Aufgabe, große Datenmengen zu organisieren, sie auffindbar zu machen und einfach zu navigieren. Hier sind einige Merkmale der funktionellsten Layouts.
Dynamisches Layout. Eine veraltete API erkennt man an ihrer statischen Dokumentation. Eine einzelne Seite oder sogar ein PDF-Dokument reichen im Jahr 2020 nicht mehr aus. Dynamische Dokumentationen lassen sich leicht durchsehen, aktualisieren und mit Lesezeichen versehen.
Sticky contents. Nein, die Navigationsleiste lenkt nicht ab und stiehlt keinen wertvollen Platz auf dem Bildschirm. Behalten Sie die Inhalte immer im Blick.
Dreispaltiges Layout. Dieses Layout wird nicht sehr häufig verwendet, ermöglicht aber eine weitere Spalte auf der rechten Seite für die Code-Beispiele. Dies ist natürlich nur sinnvoll, wenn Sie viel Text haben und den Code hervorheben wollen, damit die Benutzer nicht hin- und herblättern oder zwischen den Registerkarten wechseln müssen.
HubSpot API-Dokumente verwenden ein dreispaltiges Layout
Verwenden Sie Kontrastfarben für die Syntax. Entwickler verbringen viel Zeit damit, sich Ihre Code-Beispiele anzuschauen, also machen Sie sie lesbar und trennen Sie verschiedene Komponenten farblich voneinander
Dieses Beispiel aus den Graph-API-Dokumenten von Facebook zeigt auch, wie Sie verschiedene Registerkarten verwenden können, um zwischen SDKs zu wählen
Gespeicherter Bildlaufstatus. Dies ist ein kleines Detail, das jeder Entwickler zu schätzen weiß. Sie können auch Ankerlinks verwenden, um verschiedene Abschnitte der Seite anzugeben, falls die URL kopiert wird.
Förderung von Feedback. Ihre Dokumentationen sind Ihr wichtigstes Marketinginstrument – wenn die Leute sie mögen, werden sie Ihre API eher verwenden als die der Konkurrenz und die Community um sie herum vorantreiben. Die übliche Meldung „War diese Seite hilfreich?“ zeigt Ihnen, wie gut Sie die Fragen der Entwickler beantworten, und das Feedback-Formular wird häufig verwendet, solange Sie es einhalten.
Verlassen Sie Ihre Dokumente nicht
Veraltete Dokumente sind das größte Ärgernis der API-Nutzer. Es handelt sich auch um einen der häufigsten Fehler. Die Entwickler schreiben oft erst einige Tage nach der Veröffentlichung über Aktualisierungen und beschränken sich dabei manchmal auf ein paar Sätze. Dies geschieht, weil es keinen etablierten Prozess für die Aktualisierung von Dokumenten gibt und niemand dafür verantwortlich ist. So sorgen Sie für regelmäßige und nützliche Aktualisierungen der Dokumente.
Bereiten Sie die Dokumente vor den Aktualisierungen vor. Machen Sie es zu einem zusätzlichen Schritt in Ihrem Einführungsplan und bringen Sie sie nicht heraus, bevor Sie gut geschriebene, detaillierte und bearbeitete Absätze haben, um Ihre Aktualisierungen einzuführen.
Entfernen Sie regelmäßig veraltete Daten. Die Dokumente müssen häufig überprüft werden, mindestens einmal alle paar Monate. Durch Benutzerfeedback können Sie Unstimmigkeiten früher erkennen, und es sollte immer ein Teammitglied geben, das für die Überprüfung der Dokumente und die Reaktion auf Aktualisierungen zuständig ist.
Nutzen Sie Analysen zur Verbesserung der Dokumentationen. Standard-API-Analysen zeigen Ihnen, welche Endpunkte am häufigsten verwendet werden, sodass Sie sich auf bestimmte Teile der Dokumentation konzentrieren und mehr nützliche Informationen bereitstellen oder spezielle Tutorials erstellen können. Überwachen Sie die Anwendungsfälle, für die Ihre APIs genutzt werden, denn so können Sie das Nutzenversprechen erweitern und die Dokumentation mit mehr Möglichkeiten aktualisieren.
Große Beispiele für API-Dokumentation
Es gibt tonnenweise gute Dokumentationen, die Sie erkunden und von denen Sie lernen können. Zusätzlich zu den Beispielen, die wir in diesem Artikel vorgestellt haben, finden Sie hier einige weitere, die Sie sich ansehen sollten.
Medium-API-Dokumentation
Medium-API-Dokumente halten sich nicht unbedingt an alle Regeln, die wir heute aufgeführt haben, aber sie sind großartig für die begrenzte Funktionalität, die diese API unterstützt – das Veröffentlichen und Durchsuchen von Publikationen auf Medium. Sie werden auf GitHub geteilt, haben einen wirklich kurzen, aber klaren Inhalt mit Tonnen von Beispielen und enden jeweils mit einer Abschrift aller im Code erwähnten Parameter, einschließlich möglicher Fehler. Es ist bemerkenswert einfach, aber zuverlässig – alle Vorschläge können direkt auf GitHub gemacht werden und die Docs werden regelmäßig aktualisiert.
Mailchimp API-Dokumentation
Mailchimp ist sich bewusst, dass die meisten seiner Adressaten Marketingfachleute sind und verwendet eine Sprache, die es auch Nicht-Technikern ermöglicht zu verstehen, wie man mit seinen APIs arbeitet. Auf den ersten Blick folgt jeder Abschnitt der gleichen Struktur:
- Was ein Endpunkt tut und was der Benutzer mit dem Leitfaden tun kann
- Was Sie benötigen – alle Zugänge oder Konten, die ein Benutzer zuerst erhalten muss
- Was jede Funktion ist, mit einer Textbeschreibung, einem Codebeispiel in mehreren Sprachen und manchmal mit Screenshots der Schnittstelle.
Es gibt sogar eine Kopierschaltfläche für jedes Stück Code – ein Detail, das Nicht-Techniker sicherlich zu schätzen wissen.
Twilio API-Dokumentation
Twilio hat bekanntlich gute API-Dokumente. Obwohl die Dokumente nur die Spitze des Eisbergs der Hilfe sind, die Twilio bietet – es gibt SDKs in mehreren Sprachen und Beispiel-Apps für iOS, Android und Web. Vor allem folgen sie der dreispaltigen Logik mit dem Code direkt rechts neben der Anleitung. Die einfachsten Aktionen werden detailliert erklärt und es gibt zahlreiche Links für zusätzliche Informationen und Screenshots. Feedback wird auch über eine „Bewerten Sie diese Seite“-Schaltfläche und Links zum Support-Team und dem Tag auf StackOverflow gefördert.
Spotify API-Dokumentation
Obwohl die Web-API-Dokumente von Spotify sehr typisch sind, gibt es auf der Plattform Spotify for Developers viele zusätzliche Informationen. Es gibt Demos für grundlegende Funktionen, Mock-Apps, Live-Beispiele, die mit Spotify-APIs und -Widgets erstellt wurden, Wrapper für verschiedene Programmiersprachen und natürlich die Konsole. Die Konsole ist im Grunde eine interaktive Dokumentation, in die Sie Ihre (oder Beispiel-)Daten eingeben und Endpunkte live erkunden können. Leistungsstarke Produkte und eine solide Wissensbasis machen Spotify zu einem zuverlässigen Partner, mit dem Entwickler gerne zusammenarbeiten.
Behandeln Sie die Dokumentation mit Sorgfalt
Die Dokumentation ist der einzige Berührungspunkt, den Sie mit den meisten Ihrer Zielgruppe haben werden, also müssen Sie lernen, durch sie klar zu kommunizieren. Der beste Tipp ist, jemandem diese Aufgabe zu übertragen. Oft handelt es sich dabei um einen technischen Redakteur, der weiß, wie man sich an ein Publikum mit unterschiedlichen Kenntnissen wendet, der die Worte der Entwickler in umsetzbare Punkte übersetzen kann und der die rechtzeitige Pflege und Aktualisierung der Dokumente überwacht. Die Verwaltung einer hervorragenden Dokumentation ist jedoch auch ohne einen Experten in Ihrem Unternehmen möglich. API-Verwaltungstools wie Swagger UI, Spotlight, Apiary und Tools zur Spezifikation von Dokumenten verfügen über eine breite Funktionalität, die Ihnen dabei hilft, Dokumente zu erstellen, die von den Entwicklern geliebt werden.