Inhaltsverzeichnis
Heute freuen wir uns, wieder einmal eine Gastautorin im doctima-Blog zu begrüßen. Stephanie Steinhardt ist Dipl. Technik-Redakteur (FH) und wissenschaftliche Mitarbeiterin an der Hochschule Merseburg. Als freiberufliche Technik-Redakteurin betreut sie außerdem verschiedene Kunden z. B. aus dem Automobilbereich. In ihrem Post zeigt sie uns erste Ergebnisse aus einer gemeinsamen Forschungsarbeit mit Prof. Dr. Michael Meng und Andreas Schubert (MA) an der HS Merseburg. Doctima ist an diesem Projekt als Vernetzungspartner beteiligt.
Die Sicht von Entwicklern auf API-Dokumentation ist oftmals sehr verschieden. Während die einen davon überzeugt sind, dass guter Code keiner Dokumentation bedarf, schreiben die anderen selbst gern Dokumentation und konsultieren sie auch häufig. Die Meinungen darüber, wie sie denn aussehen soll, die perfekte API-Dokumentation, gehen ebenfalls auseinander. Es existieren unterschiedliche Ansätze zu Aussehen, Darreichung und Inhalt einer solchen.
An der Hochschule Merseburg widmet sich seit zwei Jahren ein kleines Team von Technik-Redakteuren in einem Forschungsprojekt der Optimierung von API-Dokumentation. Die Fragen nach Struktur und Inhalt der perfekten API-Dokumentation sowie nach dem Leseverhalten der Entwickler stehen dabei im Mittelpunkt der Untersuchungen. Auf Basis von 23 durchgeführten Interviews, der Erhebung von Daten aus rund 100 Fragebögen und einer Beobachtungsreihe, bei der genau verfolgt wurde, wie Entwickler Programmieraufgaben lösen, sowie unter Berücksichtigung der bereits existierenden Studien im Umfeld von Entwicklerdokumentation können wir Empfehlungen geben, die API-Dokumentationen deutlich besser und effizienter nutzbar machen.
Nicht jeder Entwickler ist wie der andere.
Entwickler unterscheiden sich nicht nur in ihrer Einstellung zur Dokumentation, in den Jahren ihrer Programmiererfahrung oder bezüglich der Systemwelt, in welcher sie zu Hause sind. Sie unterscheiden sich vor allem in ihrer Arbeitsweise. So konnten wir in unseren erhobenen Daten zwei verschiedene Ansätze identifizieren, welche vor allem bei der Einarbeitung in eine neue API deutlich hervortreten. So gibt es Entwickler, die einen eher codegetriebenen Ansatz verfolgen und nach eigener Aussage gern direkt mit einem Code-Beispiel einsteigen. Sie erarbeiten sich den Umfang einer API eher intuitiv von unten nach oben. Es gibt aber auch Entwickler, die konzeptorientiert arbeiten und sich vor der Nutzung einer neuen API zunächst einen Überblick verschaffen. Entwickler, die der Meinung sind, dass es nützlich ist, das Konzept der API in Gänze zu verstehen, auch wenn nur ein Teil der API tatsächlich zur Problemlösung genutzt wird.
Besonders deutlich traten diese Verhaltensmuster in der von uns durchgeführten Beobachtungsreihe hervor. So haben 6 der 11 beobachteten Probanden im Konzeptbereich der API-Dokumentation unserer Test-API gelesen, wohingegen die anderen 5 kaum einen Blick hineinwarfen und vorrangig auf Beispielcode fixiert waren.
Abb. 1: Absolute Zeitwerte: Recherchezeit (farbig) vs. Bearbeitungszeit (grau) der Probanden 01-11
Lesen ist nicht gleich lesen.
Trotz der gegensätzlichen Sichtweisen der Entwickler auf API-Dokumentation hat die Beobachtung gezeigt, dass im Beobachtungszeitraum von jeweils einer Stunde alle Probanden nahezu die Hälfte der Zeit mit der Recherche in der API-Dokumentation zubrachten, während die andere Hälfte für die tatsächliche Programmierung zur Lösung der Aufgaben verwendet wurde.
Wie die Analyse der entstandenen Eyetracking-Aufnahmen zeigte, scannten und überflogen die Entwickler die einzelnen Inhalte mehr, als dass sie tatsächlich Zeile für Zeile lasen. Dabei fokussierten Sie vorrangig auf die visuell hervorgehobenen Elemente, wie Hyperlinks, die Navigation und Beispielcode. Der erklärende Fließtext wurde meist nur dann gelesen, wenn aus dem Beispielcode allein keine Lösung abzuleiten war.
Das Leseverhalten schien darüber hinaus nicht nur beeinflusst von der individuellen Arbeitsweise, sondern war auch geprägt von der Einschätzung zum Schwierigkeitsgrad der gestellten Aufgabe. Bei Aufgaben, die schwieriger zu lösen schienen, waren die Probanden eher geneigt zu lesen, als bei Aufgaben, die einfacher wirkten.
Wer die Prozesse kennt, ist klar im Vorteil.
Bereits in den Interviews und in existierenden Studien kam zum Vorschein, dass mitunter alleinige Programmiererfahrung kein Garant ist für die schnelle Einarbeitung in eine neue API. Vielmehr entscheidend ist das vorhandene Domainwissen. Wer mit den zugrunde liegenden Prozessen vertraut ist, welche die API abbildet und dazu das Fachvokabular kennt, ist deutlich schneller bei der Einarbeitung und Lösung von Programmieraufgaben. Das zeigte auch unsere Beobachtungsreihe sehr eindrücklich (vgl. Abbildung 1 – Probanden 03, 04, 05,06 und 10 besaßen Domainwissen).
Demnach kommt der Vermittlung von Domainwissen in einer API-Dokumentation eine wichtige Rolle zu. Die Platzierung dieser Informationen ist mit Hinblick auf Leseverhalten und Arbeitsweise der Entwickler elementar.
Der beste Ort für wichtige Informationen in einer API-Dokumentation ist einer, den alle Entwickler tatsächlich anschauen. Auf Basis der Interviews, den Fragebögen und der Beobachtung können nur Codebeispiele dieser Anforderung genügen. Sie werden von allen Entwicklern angesehen und als Basis der eigenen Programmierung verwendet. „Verkleidet“ man wichtige Informationen als Codekommentar und setzt diese deutlich vom restlichen Code-Beispiel ab, kann man sicher sein, dass sie gesehen und, wenn kurz, auch gelesen werden. Auf ausführlichere Beschreibungen sollte zugunsten der eher konzeptorientierten Entwickler aber dennoch nicht verzichtet werden.
Abb. 2: Beispiellayout für Codekommentare im Beispielcode
Dieser konkrete Optimierungsvorschlag und die zuvor genannten Erkenntnisse sind natürlich nur ein kleiner Teil der bisher gewonnenen Forschungsergebnisse. Unsere Untersuchungen dauern im Moment noch an. Daher sind wir auch sehr interessiert an Unternehmen, die bereit sind, sich an ähnlichen Studien zu beteiligen und damit die Zahl der möglichen Probanden vergrößern.
Kontakt: stephanie.steinhardt@hs-merseburg.de
