[API как продукт] Dokumentation / Sudo Null IT News

Das ist Kapitel 30 mein kostenloses API-Buch.

Leider schenken viele API-Entwickler der Referenzdokumentation wenig Aufmerksamkeit; Die Dokumentation hingegen ist nichts weniger als das Gesicht des Produkts und der Einstiegspunkt darin. Verschärft wird das Problem dadurch, dass es unglaublich schwierig ist, aus Entwicklersicht zumindest eine zufriedenstellende Dokumentation zu schreiben.

Bevor wir zur Beschreibung der Arten und Formate der Dokumentation übergehen, möchte ich einen sehr wichtigen Punkt ansprechen: Benutzer interagieren mit Ihrer API-Hilfe auf eine völlig andere Weise, als Sie sich das vorstellen. Denken Sie daran, wie Sie selbst an einem Projekt arbeiten: Sie folgen ganz bestimmten Schritten.

  1. Ob dieser Service grundsätzlich für Ihr Vorhaben geeignet ist, muss geklärt werden (je früher desto besser!).

  2. Wenn ja, dann müssen Sie herausfinden, wie Sie ein bestimmtes Problem damit lösen können.

Tatsächlich wollen Anfänger (d. h. jene Entwickler, die mit Ihrer API nicht vertraut sind) normalerweise genau eines: Code aus vorhandenen Beispielen zusammenstellen, der ihr spezifisches Problem löst, und nie wieder darauf zurückkommen. Natürlich klingt es nicht sehr attraktiv in Bezug auf den Aufwand und die Zeit, die Sie für die Entwicklung der API und der Dokumentation dafür aufgewendet haben, aber die harte Realität sieht so aus. Das ist übrigens auch der Grund, warum Entwickler mit der Qualität Ihrer Dokumentation immer unzufrieden sein werden – da es absolut unmöglich ist, alle möglichen Optionen vorherzusehen, welche Kombinationen aus welchen Beispielen Neueinsteiger brauchen und welche konkreten Begriffe und Konzepte sich im Beispiel drehen werden für sie unverständlich erscheinen. Fügen wir dem Obigen die Überlegung hinzu, dass Nicht-Anfänger, dh Entwickler, die bereits mit dem System vertraut sind und nach Lösungen für einige komplexe Sonderfälle suchen, nur völlig nutzlose Kombinationen einfacher Beispiele sind, und im Gegenteil Benötigen Sie detaillierte Materialien zu erweiterten API-Funktionen.

Einleitende Bemerkungen

Die Dokumentation leidet oft unter bürokratischem Schreiben: Sie wird mit strenger Terminologie geschrieben (was oft das Studium eines Glossars erfordert, bevor eine solche Dokumentation gelesen werden kann) und ohne Grund aufgeblasen – so dass anstelle einer einfachen Zwei-Wort-Antwort auf die Frage eines Benutzers ein Absatz von Text erhalten wird. Wir verurteilen diese Praxis kategorisch: Eine ideale Dokumentation sollte einfach und prägnant sein, und alle Begriffe sollten mit Transkriptionen oder Links direkt im Text versehen sein (einfach bedeutet jedoch nicht Analphabeten: Denken Sie daran, Dokumentation ist das Gesicht Ihres Produkts, Grammatikfehler und Begriffsfreiheiten sind hier nicht akzeptabel ).

Denken Sie jedoch daran, dass die Dokumentation auch zum Durchsuchen verwendet wird – daher muss jede Seite genügend Sätze von Schlüsselwörtern enthalten, um in die Suche aufgenommen zu werden. Dies widerspricht etwas der Forderung nach Prägnanz und Kompaktheit, aber das ist der Weg.

Arten von Referenzmaterialien

Spezifikation / Handbuch / Referenz

Jede Dokumentation beginnt mit der formalsten Beschreibung der verfügbaren Funktionalität. Ja, diese Art der Dokumentation ist im Hinblick auf die Benutzerfreundlichkeit so nutzlos wie möglich, aber es ist unmöglich, sie nicht bereitzustellen – das Nachschlagewerk ist ein hygienisches Minimum. Wenn Sie kein Dokument haben, das alle Methoden, Parameter und Einstellungen, die Typen aller Variablen und ihre gültigen Werte, alle Optionen und Verhaltensweisen beschreibt, sind alle Optionen und Verhaltensweisen festgelegt – dies ist keine API, sondern nur eine Art Amateuraktivität.

Heute ist es auch zum Standard geworden, eine maschinenlesbare Referenz bereitzustellen – nach irgendeinem Standard, zum Beispiel OpenAPI.

Die Spezifikation sollte nicht nur formale Beschreibungen enthalten, sondern auch implizite Konventionen dokumentieren, wie beispielsweise die Reihenfolge der Ereignisgenerierung oder nicht offensichtliche Seiteneffekte von Methoden. Die Referenz sollte als die vollständigste aller möglichen Arten von Dokumentation angesehen werden: Nachdem der Entwickler die Referenz studiert hat, muss er sich mit absolut allen verfügbaren Funktionen vertraut machen. Sein wichtigster angewandter Wert ist beratend: Entwickler werden sich an ihn wenden, um einige nicht offensichtliche Probleme zu klären.

Wichtig: formale Spezifikation ist nicht die Dokumentation selbst; Dokumentation ist die Wörter, die Sie für jedes Feld und jede Methode in das Beschreibungsfeld schreiben. Ohne verbale Beschreibungen ist die Spezifikation nur gut, um zu überprüfen, ob Sie die Entitäten gut genug benannt haben, damit der Entwickler ihre Bedeutung selbst erraten kann.

Beschreibungen der Nomenklatur von Methoden werden neuerdings auch oft in Form von vorgefertigten Sammlungen von Anfragen oder Codefragmenten angelegt – insbesondere für Postman oder ähnliche Tools.

Codebeispiele

Basierend auf dem oben Gesagten sind Codebeispiele das wichtigste Werkzeug, um neue Benutzer Ihrer API zu gewinnen und zu unterstützen. Es ist extrem wichtig, Beispiele so zu wählen, dass sie Anfängern die Arbeit mit der API erleichtern; schlecht strukturierte Beispiele mindern nur die Qualität Ihrer Dokumentation. Bei der Zusammenstellung von Beispielen sind folgende Grundsätze zu beachten:

  • Beispiele sollten tatsächliche API-Nutzungsszenarien abdecken: Je besser Sie die häufigsten Anfragen von Entwicklern erraten können, desto freundlicher und einfacher zu bedienen wird Ihre API in ihren Augen aussehen;

  • Beispiele sollten prägnant und atomar sein: Das Mischen vieler verschiedener Tricks aus verschiedenen Fachgebieten in einem Codefragment verringert dessen Verständlichkeit und Anwendbarkeit erheblich;

  • der Code der Beispiele sollte so nah wie möglich an der realen Anwendung sein; Der Autor dieses Buches sah sich einer Situation gegenüber, in der ein synthetisches Stück Code, das in der realen Welt absolut bedeutungslos war, von Entwicklern gedankenlos in großer Zahl repliziert wurde.

Idealerweise sollten Beispiele mit allen anderen Arten von Dokumentationen verknüpft werden. Insbesondere sollte die Referenz Beispiele enthalten, die für die Beschreibung der Entitäten relevant sind.

Sandkästen

Beispiele werden für Entwickler viel nützlicher, wenn sie in Form von „Live“-Code präsentiert werden, der modifiziert und zur Ausführung ausgeführt werden kann. Im Fall von Bibliotheks-APIs kann dies einfach eine Online-Sandbox mit vorgefertigten Beispielen sein (bestehende Online-Dienste wie JSFiddle können auch als solche Sandbox verwendet werden); Für andere APIs kann die Sandbox-Entwicklung schwieriger sein:

  • Wenn der Zugriff auf Daten über die API bereitgestellt wird, sollte die Sandbox es Ihnen auch ermöglichen, mit echten Daten zu arbeiten – entweder mit Ihren eigenen (mit dem Profil des Entwicklers verknüpft) oder mit einem Testdatensatz.

  • Wenn die API eine Schnittstelle (visuell oder Software) zu einer Nicht-Online-Umgebung ist (z. B. Grafikbibliotheken für mobile Geräte), sollte die Sandbox ein Simulator oder Emulator einer solchen Umgebung in Form eines Online-Dienstes oder sein Eigenständige Anwendung.

Leitfaden (Tutorial)

Mit Führung meinen wir einen speziell geschriebenen, für Menschen lesbaren Text, der die Grundprinzipien der Arbeit mit der API umreißt. Das Handbuch nimmt daher eine Zwischenposition zwischen der Referenz und den Beispielen ein: Es impliziert mehr als nur das Kopieren von Codeteilen aus Beispielen und das Eintauchen in die API, erfordert jedoch weniger Zeitaufwand und Aufmerksamkeit als das Lesen der vollständigen Referenz.

Per Definition ist ein Handbuch ein solches „Buch“, in dem Sie dem Leser die Arbeit mit Ihrer API vermitteln. Ein gut geschriebenes Handbuch sollte daher grob den Prinzipien des Schreibens von Programmierbüchern folgen, d.h. Präsentieren Sie Konzepte konsistent und konsequent von einfach bis komplex. Außerdem sollte das Handbuch enthalten:

  • allgemeine Informationen zum Fachgebiet; Zum Beispiel sollte das Handbuch für Mapping-APIs einen einführenden Teil über Koordinaten und die Arbeit mit ihnen enthalten;

  • richtige Anwendungsfälle, d.h. “Happy Path”-API;

  • Beschreibungen der richtigen Reaktion auf bestimmte Fehler;

  • detaillierte Tutorials zu erweiterten API-Funktionen (natürlich mit detaillierten Beispielen).

In der Regel ist das Handbuch ein allgemeiner Block (grundlegende Begriffe und Konzepte, verwendete Notation) und eine Reihe von Blöcken für jede Art von Funktionalität, die über die API bereitgestellt wird.

Oft sticht in der Zusammensetzung der Führung das sogenannte hervor. ‘Schnellstart’ (‘Hallo, Welt!’): Das kürzeste Beispiel, das es einem Anfänger ermöglicht, zumindest eine minimale Anwendung auf der API zu erstellen. Es gibt zwei Zwecke für seine Existenz:

  • werden Sie zum Standardeinstiegspunkt, dem verständlichsten und nützlichsten Text für diejenigen, die zum ersten Mal von Ihrer API gehört haben;

  • Beziehen Sie Entwickler mit ein, lassen Sie sie den Service an einem Live-Beispiel “fühlen”.

Schnellstarts sind auch ein guter Indikator dafür, wie gut Sie bei der Identifizierung von Häufigkeitsfällen und der Entwicklung von Hilfsmethoden waren. Wenn Ihr Schnellstart mehr als ein Dutzend Codezeilen enthält, machen Sie definitiv etwas falsch.

FAQ & Wissensdatenbank

Nachdem Sie die API veröffentlicht und mit der Unterstützung von Benutzern begonnen haben (siehe vorheriges Kapitel), haben Sie auch ein Verständnis für die häufigsten Benutzerfragen. Wenn es nicht so einfach ist, die Antworten auf diese Fragen in die Dokumentation zu integrieren, ist es sinnvoll, einen eigenen Abschnitt mit häufig gestellten Fragen (FAQ) zu erstellen. Der FAQ-Bereich muss folgende Kriterien erfüllen:

  • echte Benutzerfragen beantworten;

    • Sie können oft solche Abschnitte finden, die nicht auf der Grundlage echter Anfragen zusammengestellt wurden und hauptsächlich den Wunsch des API-Eigentümers widerspiegeln, noch einmal einige wichtige Informationen zu übermitteln; Natürlich ist eine solche FAQ bestenfalls nutzlos und schlimmstenfalls lästig; Ideale Beispiele für die Implementierung dieses Anti-Musters finden Sie auf der Website jeder Bank oder Fluggesellschaft);

  • sowohl die Frage als auch die Antwort sollten prägnant und klar formuliert sein; In der Antwort ist es akzeptabel (und sogar wünschenswert), auf die relevanten Abschnitte des Leitfadens und des Handbuchs zu verlinken, aber die Antwort selbst sollte ein paar Absätze nicht überschreiten.

Darüber hinaus eignet sich der FAQ-Bereich sehr gut, um die Hauptvorteile Ihrer API explizit zu kommunizieren. In Form eines Frage-Antwort-Paares können Sie anschaulich beschreiben, wie Ihre API komplexe Probleme schön und komfortabel löst (oder zumindest im Gegensatz zu den APIs der Konkurrenz überhaupt löst).

Wenn Sie technischen Support öffentlich anbieten, ist es sinnvoll, Fragen und Antworten als separaten Service zu speichern, um eine Wissensbasis zu bilden, d.h. eine Reihe von “lebendigen” Fragen und Antworten.

Offline-Dokumentation

Obwohl wir online in der Welt der Gewinner leben, ist die Offline-Version der Dokumentation in Form eines generierten Dokuments dennoch sinnvoll – vor allem als „Abguss“ des aktuellen Stands der API zu einem bestimmten Zeitpunkt.

Probleme mit doppelten Inhalten

Ein großes Problem für die Lesbarkeit der Dokumentation ist die API-Versionierung: Viele Texte für verschiedene Versionen ähneln sich bis zur Ununterscheidbarkeit. Es ist sehr schwierig, sowohl intern als auch extern eine qualitativ hochwertige Suche nach einer solchen Datenmenge zu organisieren. Gute Umgangsformen in dieser Hinsicht sind:

  • explizite und auffällige Hervorhebung auf den Dokumentationsseiten der API-Version, auf die es sich bezieht;

  • ein klarer und auffälliger Hinweis auf das Vorhandensein einer aktuelleren Version der Seite für neue APIs;

  • Pessimierung (bis hin zum Indizierungsverbot) der Dokumentation für veraltete API-Versionen.

Wenn Sie Abwärtskompatibilität unterstützen, können Sie versuchen, dieselbe Dokumentation für alle Versionen der API beizubehalten. In diesem Fall müssen Sie für jede Entität angeben, von welcher Version der API ihre Unterstützung stammt. Hier tritt jedoch das Problem auf, dass es äußerst schwierig ist, eine Dokumentation für eine bestimmte (veraltete) Version der API zu erhalten (und im Allgemeinen zu verstehen, welche Funktionen eine bestimmte Version der API bereitstellt). (Aber die oben erwähnte Offline-Dokumentation kann dabei helfen.)

Das Problem wird komplizierter, wenn Sie die Dokumentation nicht nur für verschiedene API-Versionen, sondern auch für verschiedene Umgebungen/Plattformen/Programmiersprachen pflegen – nehmen wir an, Ihre visuelle Bibliothek unterstützt sowohl Android als auch iOS. In dieser Situation sind beide Versionen der Dokumentation völlig gleichwertig, und es ist unmöglich, eine von ihnen zum Nachteil der anderen herauszuheben.

In diesem Fall müssen Sie eine von zwei Strategien wählen:

  • wenn die Hilfeinhalte für alle Plattformen komplett identisch sind, d.h. nur die Syntax des Codes ändert sich – Sie müssen die Fähigkeit vorbereiten, Dokumentation auf allgemeine Weise zu schreiben: Dokumentationsartikel sollten Codebeispiele (und möglicherweise einige Hinweise) für alle unterstützten Plattformen gleichzeitig enthalten;

  • Wenn sich der Inhalt dagegen erheblich unterscheidet (wie im erwähnten Android/iOS-Fall), können wir nur anbieten, die Seiten so weit wie möglich zu verbreiten, bis hin zur Einrichtung verschiedener Seiten: Die gute Nachricht ist, dass die Entwickler fast benötige immer nur eine der Versionen, eine andere Plattform ist ihr absolut uninteressant.

Dokumentationsqualität

Es ist wichtig zu beachten, dass die Dokumentation so bequem und nützlich wie möglich ist, wenn Sie sie selbst als eines der Produkte der API-Servicelinie betrachten – was bedeutet, dass Sie das Benutzerverhalten analysieren (auch automatisiert), Feedback sammeln und verarbeiten, Legen Sie KPIs fest und arbeiten Sie an deren Verbesserung.

War dieser Artikel hilfreich für Sie?

Ja Nein

Similar Posts

Leave a Reply

Your email address will not be published.