Den Teil schreiben, den der Generator nicht kann
Erzeugte Doku beantwortet „was nimmt dieser Endpunkt entgegen“. An dieser Frage ist noch nie jemand hängen geblieben.
API Documentation erzeugt aus Ihren Sammlungen und gibt Ihnen darüber einen Rich-Text-Editor, Versionsverwaltung, Code-Snippet-Erzeugung, PDF-Export und teilbare Links.
Die erzeugte Hälfte ist vollständig und korrekt und hilft für sich genommen niemandem. Was eine Entwicklerin blockiert, ist nie die Parameterliste.
Ordnen Sie das Dokument für eine Erstleserin
Endpunktlisten sind meist alphabetisch — die Reihenfolge, die niemandem dient. Bringen Sie das Dokument in die Reihenfolge, in der jemand integriert:
- Wie man sich authentifiziert, mit einem vollständigen funktionierenden Beispiel.
- Der eine Aufruf, der beweist, dass die Einrichtung stimmt — die kleinstmögliche Anfrage, die etwas zurückgibt.
- Der Hauptablauf in der Reihenfolge, in der er passiert.
- Alles Übrige alphabetisch, denn ab da sucht die Leserin, statt zu lesen.
Wer einen erfolgreichen ersten Aufruf erreicht, wird geduldig. Wer sich in zehn Minuten nicht authentifizieren kann, schreibt den Support an und bleibt verärgert.
Dokumentieren Sie die Fehler, nicht den Erfolg
Jede erzeugte Doku beschreibt die 200. Fast keine beschreibt die 409, die bedeutet, dass die E-Mail schon registriert ist, oder was der Client damit tun soll — wiederholen, eine Meldung zeigen, auf einen anderen Aufruf ausweichen.
Schreiben Sie die Fehlertabelle von Hand. Sie ist der meistgelesene Abschnitt und der einzige, der Supportgespräche verkürzt.
Wann man eine Version schneidet
Versionsverwaltung verdient sich ihren Platz an dem Tag, an dem jemand außerhalb Ihres Teams gegen die API baut. Schneiden Sie dann eine Version, nicht zu einem Release-Meilenstein.
Der Grund ist praktisch: Ändern Sie später ein Feld, braucht die Person, die im letzten Quartal integriert hat, das Dokument in seinem damaligen Zustand — nicht einen Changelog-Eintrag, der erklärt, dass sich etwas verschoben hat. Einen Link in eine bestimmte Version zu teilen kostet nichts und beendet die Diskussion, bevor sie entsteht.
Für alles mit externen Lesern: Link teilen statt PDF exportieren. Der Link folgt der Version; ein PDF wird am Tag nach dem Versand falsch.
Häufig gestellte Fragen
In welcher Reihenfolge sollte die Dokumentation stehen?
Authentifizierung mit vollständigem Beispiel, dann der kleinste Aufruf, der die Einrichtung beweist, dann der Hauptablauf in Reihenfolge, dann alles Übrige alphabetisch. Von oben alphabetisch dient niemandem, der zum ersten Mal integriert.
Was sollte ich von Hand schreiben?
Die Fehler und den Grund, warum es jeden Endpunkt gibt. Parameter deckt der Generator vollständig ab; an einer Parameterliste ist noch nie jemand hängen geblieben, an einem unerklärten 409 alle.
Wann sollte ich eine neue Version schneiden?
An dem Tag, an dem jemand außerhalb des Teams gegen die API zu bauen beginnt — nicht zu einem Release-Meilenstein. Diese Person braucht das Dokument, wie es bei der Integration war, nicht den Hinweis, dass ein Feld umgezogen ist.
