Allgemein

Ergebnisse der Umfrage:
Was muss gute API-Dokumentation leisten?

Im April 2016 riefen wir an dieser Stelle zur Teilnahme an einer Umfrage eines Forschungsprojektes der Hochschule Merseburg zum Thema API-Dokumentation auf. Jetzt haben wir die Ergebnisse aus erster Hand vorliegen. Diese möchten wir euch nicht vorenthalten. Lest selbst, was eine gute API-Dokumentation leisten muss, was sie kennzeichnet und welche typischen Probleme bei der Einarbeitung in eine API auftauchen können. Wir danken euch für die Teilnahme an der Umfrage und Herrn Prof. Meng für die Bereitstellung der Ergebnisse.

Was muss gute API-Dokumentation leisten? Erste Ergebnisse einer Umfrage unter Softwareentwicklern

APIs sind ein zentrales Element vieler moderner Softwarearchitekturen. Dass gute API-Dokumentation ein zentraler Faktor ist, der die Verbreitung und letztendlich den Erfolg von APIs wesentlich beeinflusst, würde vermutlich niemand ernsthaft bestreiten. Oder doch? Bislang liegen nur wenige Daten vor, die Auskunft darüber geben, welche Informationsquellen Entwickler bei der Einarbeitung in eine neue APIs tatsächlich nutzen, wie hilfreich diese Informationsquellen eingeschätzt werden und welche Eigenschaften gute API-Dokumentation aus Sicht von Entwicklern sind. Um Fragen wie diese evidenzbasiert beantworten zu können, hat unsere Arbeitsgruppe an der Hochschule Merseburg im Frühjahr diesen Jahres eine Umfrage unter Entwicklern gestartet – zur Teilnahme an der Umfrage hatte auch die JUG Saxony aufgerufen. Der JUG Saxony und allen Teilnehmern an der Umfrage an dieser Stelle ein herzliches Dankeschön für die Unterstützung! Nun liegen erste Ergebnisse vor, über die wir hier kurz berichten wollen.

Hier geht es weiter…

Hintergrunddaten zu den Umfrageteilnehmern

  • Insgesamt erreichten uns 112 Rückmeldungen: von 104 männlichen und 8 weiblichen Entwicklern. Die durchschnittliche Berufserfahrung als Entwickler beträgt 12 Jahre, der Medianwert liegt bei 10.
  • 68 Teilnehmer gaben an, in letzter Zeit regelmäßig mit Java gearbeitet zu haben, gefolgt von Javascript (54 Nennungen) und C# (41 Nennungen).
  • Korrespondierend damit stuften die Umfrageteilnehmer die eigenen Kenntnisse abhängig vom API-Typ auf einer Skala von 1 („keine Erfahrung“) bis 5 („viel Erfahrung“) für klassenbasierte APIs als eher hoch ein (M=4,42). Web APIs erreichten hier den zweiten Platz mit einem Mittelwert von 3,62.

Typische Probleme bei der Einarbeitung in eine API

Entwickler stehen immer wieder vor der Aufgabe, sich in neue APIs einzuarbeiten. Worin liegen dabei typische Probleme und Schwierigkeiten? In unserer Umfrage hatten wir für die Beantwortung dieser Frage 12 Antwortmöglichkeiten vordefiniert, die durch eigene Angaben ergänzt werden konnten. Mehrfachnennungen waren möglich.

  • Dokumentationsbezogene Probleme rangierten hier klar auf den vorderen Plätzen: „fehlerhafte oder unvollständige Dokumentation“ (69 Nennungen) und „unverständliche Dokumentation“
    (58 Nennungen).
  • Als problematisch benannt wurden überdies „Schwierigkeiten beim Aufsetzen/Einbinden der API“ (45 Nennungen) und „fehlendes Verständnis für Anwendung der API“ (39 Nennungen). Als typische erste Frage bei der Einarbeitung kristallisierte sich zudem heraus „Was kann ich mit der API machen / nicht machen?“ (60 Nennungen). Auf diese Fragen muss API-Dokumentation also zuallererst und in verständlicher Form Antworten geben – offensichtlich ist das aber in vielen Fällen noch nicht so.

Rolle unterschiedlicher Informationsquellen

Antworten auf Problemstellungen bei der Einarbeitung in eine API geben natürlich nicht nur klassische, vom API-Anbieter bereit gestellte Dokumentationsbestandteile wie z. B. die API-Referenz oder Tutorials. Suchmaschinen wie Google versprechen einen kürzeren Weg hin zur gesuchten Antwort, man kann Kollegen und Freunde um Rat fragen oder einfach versuchen, das Problem im „trial and error“-Verfahren selber zu lösen.

  • Nicht ganz überraschend sind Suchmaschinen wie Google für die meisten Teilnehmer (48%) tatsächlich die erste Option, um Hilfe im Problemfall zu erhalten. Dennoch ist die Bereitschaft, klassische Dokumentationsquellen zu nutzen, ebenfalls sehr hoch: für 33% der Teilnehmer ist das Nachschlagen in der Dokumentation die bevorzugte Option im Problemfall, für 47% der Befragten immerhin die zweite Option.
  • Welche Dokumentationsbestandteile werden dabei besonders häufig genutzt? Während der Einarbeitung vor allem Codebeispiele (96 Nennungen), aber auch Tutorials (72 Nennungen) und die API-Referenz (71 Nennungen). Beim Lösen täglicher Programmieraufgaben nach erfolgreicher Einarbeitung wird vor allem auf die API-Referenz zugegriffen (90 Nennungen), Codebeispiele bleiben ebenfalls wichtig (63 Nennungen), Tutorials spielen dann kaum noch eine Rolle (17 Nennungen).
  • Ausschließlich konzeptorientierte Dokumente, wie z. B. ein Architekturüberblick oder ein Technical Whitepaper, spielen sowohl bei der Einarbeitung als auch bei der späteren Anwendung der API im Programmieralltag eine eher untergeordnete Rolle. Information zur Architektur und zum Design einer API sollte daher – sofern sie für die erfolgreiche Verwendung der API notwendig ist – in Codebeispiele oder Tutorials integriert werden, um Beachtung zu finden.

Was kennzeichnet gute API-Dokumentation?

Auch für diese Frage hatten wir unterschiedliche Antwortoptionen vorgegeben, die jeweils auf einer Skala von 1 („unwichtig“) bis 5 („sehr wichtig“) bewertet werden sollten.

Eigenschaften_guter_APi-Doku

Interessant ist aus unserer Sicht, dass klassische Qualitätsmerkmale für Dokumentation wie Aktualität und Vollständigkeit auch aus Sicht von Entwicklern im Kontext von API-Dokumentation höchste Relevanz haben. Grund genug also, dokumentationsbezogene Tätigkeiten von geschultem Personal erledigen oder überwachen zu lassen und bei der Softwareentwicklung hohe Priorität einzuräumen. Gefragt haben wir übrigens auch, ob Entwickler selber gerne dokumentieren: Immerhin 46% haben die Frage bejaht. Darauf lässt sich aufbauen.

Wo kann ich mehr erfahren?

Einen vollständigen Überblick über die Ergebnisse unserer Umfrage und die Ergebnisse weiterer Begleitstudien zum Thema API-Dokumentation präsentieren wir auf der Jahrestagung der Gesellschaft für Technische Kommunikation (tekom e. V.) am 11. November 2016 in Stuttgart und auf der „Write the Docs − Europe“−Konferenz, die vom 18. − 20. September 2016 in Prag stattfindet. Für Fragen, Kommentare und Kritik sind wir sehr dankbar – schreibt einfach an michael.meng@hs-merseburg.de