Blog

tekom-Impressionen Teil 2: API-Dokumentation und die VUKA-Welt

Daniela Herbold und Ulrike Parson berichten über Leitlinien für eine optimierte API-Dokumentation sowie Lösungsansätze für eine innovative Personalführung. mehr ...

tekom-Impressionen Teil 1: Improvisationstechniken, Fluff Hunt und Videos

Auf dem Weg zur Konferenz sehe ich an der Fassade des Stuttgarter Bahnhofs ein Zitat von Hegel: „daß diese Furcht zu irren schon der Irrtum selbst ist“. Genau darum ging es in Anthonys Apodacas Vortrag am Morgen des zweiten Konferenztages. mehr ...

My first time at tekom

I got back from Stuttgart last night and it is safe to say that after three days of action-packed presentations, writing an article is not in the realm of possibilities right now as I try to connect one synapse with another. mehr ...

Eine Tasse auf Reisen #4 - die Auflösung

In welcher Stadt wurde die parson-Tasse fotografiert, haben wir Anfang September gefragt. Die Frage war knifflig. Trotzdem kamen die meisten auf die richtige Antwort: In Chicago, USA. mehr ...

Flipped Classroom: Schulungen effizienter gestalten

Es kostet nicht nur Zeit, in einer Präsenzschulung auf die häufig sehr unterschiedlichen Kenntnisse der Teilnehmer einzugehen. Auch besteht die Gefahr, dass sich Teilnehmer mit höheren Vorkenntnissen langweilen, während sich diejenigen mit geringem Vorwissen überfordert fühlen. mehr ...
Suchen

API-Dokumentation – Was wir von Entwicklern lernen können

Ein Gastbeitrag von Stephanie Steinhardt

Befragt man Entwickler nach API-Dokumentation, tun sich ziemlich schnell zwei unterschiedliche Lager auf. Es gibt Entwickler, die davon überzeugt sind, dass guter Code überhaupt keiner Erklärung bedarf, und natürlich auf der anderen Seite auch jene Entwickler, die häufig Dokumentation lesen und sie auch selbst gern schreiben. Ebenfalls verschiedenste Meinungen und Ansätze existieren bezüglich Aussehen, Darreichung und Inhalt einer perfekten API-Dokumentation.

An der Hochschule Merseburg forscht seit zwei Jahren ein kleines Team aus Technischen Redakteuren an der Optimierung von API-Dokumentation. Fragen nach den Inhalten und dem Aufbau einer guten API-Dokumentation werden dabei genauso intensiv untersucht wie die Zielgruppe – die Softwareentwickler – selbst.

Stephanie SteinhardtStephanie Steinhardt ist wissenschaftliche Mitarbeiterin an der Hochschule Merseburg und freiberufliche Technik-Redakteurin

Mithilfe von Interviews, einer Fragebogenuntersuchung und einer Beobachtungsreihe, bei der direkt verfolgt wurde, wie Entwickler Programmieraufgaben lösen, hat sich inzwischen, auch im Hinblick auf bereits bestehende Studien im Bereich der Entwicklerdokumentation, ein ziemlich genaues Bild ergeben zu den Anforderungen von Entwicklern an gute API-Dokumentation. Aus diesen Anforderungen lassen sich Optimierungsvorschläge ableiten.

Entwickler: Verschieden

Entwickler unterscheiden sich natürlich in ihrer Programmiererfahrung und hinsichtlich der Systemwelt, in der sie zu Hause sind. Mithilfe unserer Interviews, des Fragebogens und der Beobachtungsreihe konnten wir darüber hinaus auch zwei ganz verschiedene Arbeitsweisen der Entwickler identifizieren. Gerade dieser Unterschied, der sich vor allem auf das Leseverhalten auswirkt, muss bei der Erstellung von API-Dokumentation berücksichtigt werden.

Es gibt Entwickler, die sich eher intuitiv in eine neue API einarbeiten und ausgehend von einem Beispiel starten. Sie steigen bevorzugt direkt ein und erarbeiten sich den Umfang der API ausgehend vom Code von unten nach oben. Auf der anderen Seite gibt es Entwickler, die es nützlich finden, die API in Gänze zu verstehen. Sie lesen vor dem Start zunächst konzeptionelle Informationen und erarbeiten sich die Inhalte eher von oben nach unten. Diese Verhaltensmuster wurden vor allem in der von uns durchgeführten Beobachtungsreihe sichtbar (vgl. Abbidlung 1). Von den 11 beobachteten Probanden haben nur 6 die konzeptionellen Informationen der getesteten Herstellerdokumentation angesehen und teilweise gelesen. Die anderen 5 Entwickler haben keinen Blick in den Teil „Concepts“ geworfen.

Blog API Doku Abb 1Abb. 1: Absolute Zeitwerte: Recherchezeit (farbig) vs. Bearbeitungszeit (grau) der Probanden 01-11

Generell lasen die Entwickler die Inhalte einer Seite oftmals nicht nacheinander, sondern scannten nur über die Seite, wie die Analyse der entstandenen Eyetracking-Aufnahmen ergab. Besondere Aufmerksamkeit bekamen dabei die visuell hervorgehobenen Elemente wie Hyperlinks, Beispielcode und die Navigation. Tatsächlich gelesen wurde meist nur, wenn aus dem Beispielcode keine Problemlösung abzuleiten war. Dieses Verhalten wurde auch beeinflusst von der individuellen Einschätzung des Schwierigkeitsgrades der Aufgabe. Empfanden die Entwickler die Aufgabe als schwer lösbar, waren sie eher geneigt zu lesen als bei Aufgaben, die ihnen leichter erschienen.

Struktur: Inhaltlich

Im Hinblick auf die Arbeitsweisen und das Leseverhalten der Entwickler wird schnell klar, dass dem Aufbau und der Struktur einer API-Dokumentation große Bedeutung zukommt. Die Unübersichtlichkeit wurde auch im Fragebogen als häufigster Mangel weit vor anderen Mängeln, wie beispielsweise einer zu komplexen Dokumentstruktur, benannt (vgl. Abbildung 2). Um die Komplexität etwas zu mindern, hat sich heute zu weiten Teilen eine Bündelung nach Dokumenttypen durchgesetzt. Man findet die Getting Started-Dokumente, Developer Guides, Referenzen, Konzepte und Beispiele. Doch ist diese Klassifizierung nicht immer hilfreich.

Blog API Doku Abbildung 2Abb. 2: Häufigste Mängel von API-Dokumentation, Diagramm zeigt die Anzahl der Nennungen - wählbar waren 3 Optionen (113 Entwickler haben an Fragebogenuntersuchung teilgenommen)

In unserer Beobachtungsreihe wurde offensichtlich, dass die Entwickler nicht eindeutig zuordnen konnten, in welchem Dokumenttyp ihre persönliche Fragestellung beantwortet wird. Worin liegt der Unterschied zwischen einem Getting Started, einem Tutorial oder Rezept? Wir als Technische Redakteure können die feinen Nuancen unterscheiden, doch stammen die Entwickler nicht aus unserer Welt der Klassifizierung von Textsorten und Informationsarten.

Für Entwickler ist es weniger entscheidend, dass die Informationen in kleine Säcke zusammen geschnürt und damit vermeintlich übersichtlich präsentiert werden. Sie sind allein auf der Suche nach Antworten zu ihren Fragen. Sie möchten möglichst schnell zum Ziel gelangen. Die Frage danach, ob die gesuchten Inhalte in ein Getting Started, die Referenz oder doch in ein Tutorial oder gar Konzept sortiert wurden, hält auf und ist bei der Suche nach Lösungen oft nicht hilfreich.

Auch hat die Beobachtungsreihe gezeigt, dass Bereiche, deren Titel die Entwickler nicht klar interpretieren konnten, im Fall unserer Studie z. B. der Begriff „Recipe“, komplett gemieden wurden, obwohl genau dort die gesuchte Information zu finden war.

Allerdings müssen gerade bei größeren API-Dokumentationen die Informationen geclustert werden, da sonst höchstwahrscheinlich überhaupt nichts mehr gefunden werden kann. Ausgehend davon, dass Entwickler immer auch ein spezifisches Problem mit der API lösen wollen, ist eine inhaltliche Strukturierung sinnvoll. Nehmen wir beispielsweise eine Paketversand-API. Hier wäre es sinnvoll, nicht nach Getting Started, Konzept oder Referenz zu untergliedern, sondern vielmehr das Liefern von Paketen selbst zum Mittelpunkt des Geschehens zu machen. So könnte die API nach Dienstleistern, Sendungen, Adressen und Services sortiert werden.

Die Möglichkeiten sich einen globalen Überblick zu verschaffen und einen leichten Einstieg zu unterstützen, dürfen natürlich dennoch nicht fehlen. So müssen beispielsweise die Entscheider für oder gegen eine API sehen können, was die API kann und bietet, wie sie arbeitet und integriert wird. Diese Informationen müssten der inhaltlichen Gliederung auf gleicher Ebene vorangestellt werden, beispielsweise als Überblick. Doch auch hier lohnt sich ein sprechender Name als Titel, der anzeigt, was in diesem Überblick tatsächlich zu erwarten ist. Dies gilt ebenfalls für die Integration der API. Viele Entwickler in Interview und Fragebogen nannten vor allem die ersten Schritte in einer API als die schwierigsten. Wenn es erst einmal „läuft“, kommen die Entwickler auch ohne viel Dokumentation zurecht. Demnach sollten auch diese Informationen gebündelt, ähnlich eines Getting Started zur Verfügung stehen.

Navigation: Elementar

Die Schwierigkeiten, API-Dokumentationen zu strukturieren, werden oftmals durch eine inkonsistente Navigation weiter verschärft. Nicht selten fanden wir bei aktuellen API-Dokumentationen Navigationsleisten, die beim Scrollen des Inhalts verschwanden, vorangestellte Inhaltsverzeichnisse oder aber Navigationsstrukturen, die nicht alle Kapitelebenen abbilden. Nach wenigen Klicks befanden wir uns im Niemandsland und kamen nur noch mithilfe der Browserschaltflächen zurück zum Ausgangspunkt.

Wie bei der Webgestaltung gilt es auch bei der Navigation für eine API-Dokumentation verschiedene Kriterien zu beachten. Breadcrumb-Menüs können gute Dienste leisten, genau wie Navigationsleisten, die sich ein- und ausklappen lassen, angelehnt an das Strukturbaum-Prinzip von klassischen Online-Hilfen. Des Weiteren sollte die Navigation stets sichtbar sein, sodass der Leser immer weiß, an welcher Stelle er sich in der Gesamtstruktur befindet.

Blog API Dokumentation Abbildung 3Abb. 3: Übersichtlicher Gesamteindruck mit klarer Navigationsstruktur, optische Trennung zwischen Codebeispielen und erklärendem Text (Quelle: https://developers.paymill.com/API/index)

Diese Transparenz fehlt vielen aktuellen API-Dokumentationen. Oftmals sind auch die Wege der Navigation zu vielfältig, sodass der Leser schon durch die schiere Anzahl der Möglichkeiten überfordert ist. Es gilt also eine Balance zu finden zwischen strenger einspuriger Führung, von der Entwickler sich vielleicht bevormundet fühlen, und multiplen Ansätzen mit z. B. grafischen Menüs zur Vorauswahl der Sprachen, Dokumenttypen, Versionen usw., die bei aller innewohnenden Flexibilität auch sehr schnell für Verwirrung sorgen können.

Domainwissen: Unverzichtbar

Was bereits andere Studien und ebenso unsere Interviews als Ergebnis hervorbrachten, bestätigte auch unsere Beobachtungsreihe eindrucksvoll. Die Entwickler, die bereits Hintergrundwissen zur verwendeten Test-API hatten, konnten die gestellten Aufgaben viel schneller lösen als Entwickler mit ähnlich langer Programmiererfahrung aber ohne die entsprechende Sachkenntnis. Die Test-API der Beobachtungsreihe stammte aus dem e-Commerce-Umfeld und konnte nahezu problemlos von den Entwicklern bewältigt werden, die selbst im Bereich e-Commerce tätig waren (vgl. Abbildung 1 – die Probanden 03, 04, 05, 06 und 10 stammten aus dem e-Commerce-Umfeld).

Somit kommt der Vermittlung von Domainwissen offenbar eine entscheidende Rolle bei der schnellen Einarbeitung in eine neue API zu. Doch wo muss dieses Wissen platziert werden, wenn wir doch Abstand nehmen von einer Gliederung nach Textsorten und damit verzichten auf einen Teil „Konzept“? Mit dem Blick auf die Arbeitsweisen und das Leseverhalten der Entwickler müssen Hintergrundinformationen und andere wichtige Informationen genau dort platziert werden, wo alle Entwickler einen Blick drauf werfen.

Im Hinblick auf die Ergebnisse von Interview, Fragebogen und Beobachtung können nur Codebeispiele diese Aufgabe erfüllen. Beispielcode wird generell von allen Entwicklern positiv bewertet und wurde auch in der Beobachtungsreihe von allen Probanden angesehen und als Ausgangspunkt für die eigene Programmierung verwendet. „Verkleidet“ man also die wichtigen Informationen als Codekommentare und hebt diese optisch vom restlichen Beispielcode ab, ist sicher, dass diese Inhalte gesehen und auch gelesen werden (vgl. Abbildung 4).

Trotzdem sollten natürlich auch immer ausführlichere Beschreibungen vorhanden sein, um die eher konzeptorientierten Entwickler ebenfalls zu berücksichtigen.

Blog API Dokumentation Abbildung 4Abb. 4: Beispiellayout für Codekommentare im Beispielcode (adaptierter Inhalt, basierend auf https://developers.shipcloud.io/recipes/)

Dieser konkrete Vorschlag und die zuvor genannten Erkenntnisse sind natürlich nur ein kleiner Teil der bereits vergangenen Forschung. Im Moment dauern die Untersuchungen noch an. Wir sind daher immer interessiert an Firmen, die sich an Studien beteiligen möchten und damit die Anzahl möglicher Probanden weiter vergrößern.

Stephanie Steinhardt, Dipl. Technik-Redakteur (FH), Wissenschaftlicher Mitarbeiter der Hochschule Merseburg und freiberuflicher Technik-Redakteur. Die Ergebnisse stammen aus der gemeinsamen Forschungsarbeit mit Prof. Dr. Michael Meng und Andreas Schubert (MA).

Lesen Sie auch zum Thema unseren Wissensartikel Documentation for Software Engineers. 

Kommentar schreiben


« Zurück zur Übersicht
  • facebook
  • linkedin
  • xing