Wir machen Sie darauf aufmerksam, dass unsere Website über Cookies personenbezogene Daten von Ihnen erhebt. Mehr Informationen Zustimmen und fortfahren

13.06.2018

API Dokumentation (Schnittstellen-Dokumentation) zielgruppengerecht erstellen.

Dr. Michael Meng, HS Merseburg

APIs (Programmierschnittstellen für Anwendugen) sind ein wichtiges Element für Entwickler. Ebenso wichtig ist eine gute Dokumentation. Dr. Michael Meng von der HS Merseburg informierte uns.

21 Teilnehmer interessierten sich für die ersten Ergebnisse einer Studie für API Dokumentation der Hochschule Merseburg.

In seinem theoretischen Einstieg in die API Dokumentation grenzte Dr. Meng zwei verschiedene API-Typen von einander ab - klassenbasierten APIs und REST-APIs. Die Studie befasst sich mit der REST-API.

Die Bedeutung der Dokumentation für APIs nimmt immer mehr zu, so Meng. Vor allem in den USA und Kanada gibt es viel Forschung zu dem Themengebiet. Hier verwies Dr. Meng auf Robillard und die Developer Journey von Kathleen DeRoo. DeRoo verweist darauf, dass die API-Dokumentation alle Phasen der Developer Journey enthalten sollte.

 

Die Studie zur Optimierung von API Dokumentation von Meng und Steinhardt setzte sich aus mehreren Stufen zusammen:

Befragung von Entwicklern, zur Ermittlung der Probleme, die mit API-Dokumentation auftreten. Daraus wurden dann Schwerpunkte gebildet - von fehlerhafter oder unvollständiger Dokumentation bis zu Schwierigkeiten beim Debuggen. Dabei wurden zwei unterschiedliche Arbeitsweise von Entwicklern festgestellt - Top down zu Codeorientierte. Meng sprach hier von 2 Personas die auch schon in anderen Studien so ermittelt wurden. Für beide Personas gilt: Mangelnde API-Dokumentation ist das größte Hindernis für die API-Entwickler und die Kapitel zu Hintergrundwissen werden wenig gelesen.

API-Dokumentation bestehen meistens textorientierte Bausteine: Referenzhandbuch, Kochbuch, Entwickler Guide, Beispiele und FAQ.  Mit verschiedene Beispiele für API-Dokumentation und Plattformen zeigt Meng auf, wie unterschiedlich sie aufbereitet ist und hinterfragte auch warum StackOverflow, eine Plattform für Entwickler, die APIs nur mit Beispielen dokumentierte, scheiterte.

ERGEBNISSE

Was also benötigt eine API-Dokumentation. Nach der Bedarfsermittlung und Analyse der Entwicklungsarbeit wurden Optimierungsvorschläge abgeleitet und mit einem Usabilitytest empirisch getestet. Die Ergebnisse geben erste Hinweise zur Optimierung, müssen aber noch weiter verifiziert werden, so Meng. Das wichtigste Ergebnis: Fehlende Domänenkenntnis wirkt sich signifikant auf die Geschwindigkeit bei der Problemlösung aus.

 

Die wichtigsten Aussagen für die Erstellung einer guten API-Dokumentation:

Die Inhalte müssen vollständig und fehlerfrei sein.

Die Navigation soll nicht textorientiert erfolgen, sondern sich an Usecases der API orientieren.

Es ist besser ein Thema auf einer lange Seiten aufzubereiten als auf mehreren verlinkten Seiten. Domänenwissen soll in den Usecases "nebenbei" vermittelt werden. Mit Grafiken und Schaubilder soll das nötige Hintergrundwissen ansprechend aufbereitet werden.

Redundanzen sind notwendig. So soll derselbe Informationstext in der Beschreibung und auch im Code verwendet werden. Damit können beide Entwicklertypen bedient werden.

Codebeispiele müssen vollständig sein und nach dem Kopieren ohne weitere Anpassung funktionieren und nicht in eine zeitraubende Fehlersuche münden.

Der Code für die beschriebene Funktion soll innerhalb des Codebeispiels hervorgehoben werden.

 

FAZIT

Die lebhafte Diskussion und Fragen zeigten auf, dass das Thema API Dokumentation immer wichtiger wird und Technische Redakteure sich dafür verbindliche Standards wünschen. Ein einheitliches Vorgehen und mehr Aussagen zur richtigen Inhaltsaufbereitung und Navigation werden gewünscht. Inwieweit sich die vorliegenden Ergebnisse auf die Dokumentation von komplexen APIs übertragen werden können, muss noch geprüft werden.