Was brauchen Entwickler wirklich? – Optimierung von Software-Entwicklerdokumentation

Software-Entwicklerdokumentation ist wichtig, findet aber im Redaktionsalltag oft wenig Beachtung. Eine Ursache dafür könnte sein, dass es Unsicherheiten gibt in Bezug auf Inhalt und Darreichungsform dieser Dokumentationsart. Welche Informationen brauchen Entwickler wirklich und wie müssen diese aufbereitet werden? Fragen wie diese stehen im Mittelpunkt einer empirischen Erhebung unter Softwareentwicklern zu ihren Erwartungen an hilfreiche Entwicklerdokumentation.

Einleitung

Softwareentwicklerdokumentation ist im Alltag von Technischen Redakteuren noch nicht wirklich angekommen. Vielleicht liegt das daran, dass der Inhalt von Entwicklerdokumentation als sehr schwierig gilt und zusätzliche Programmierkenntnisse oder aber zu viel Recherche und Befragung der Entwickler notwendig wären, um wirklich sinnbringend für andere Experten zu schreiben. Ein Blick in einschlägige Fachliteratur zum Thema Entwicklerdokumentation offenbart zudem recht schnell, dass eine eindeutige Terminologie fehlt und somit scheinbar kein gleiches Verständnis darüber herrscht, was überhaupt Teil einer Entwicklerdokumentation sein soll. Auch dies könnte dazu beitragen, dass Entwicklerdokumentation in Aufbau und Struktur noch keinem festen Standard folgt.

Auf quellcodenaher Ebene findet man noch gleiche Begriffe, die Gleiches meinen. So scheint klar zu sein, was unter einer API-Referenz, einem Klassendiagramm oder den Codekommentaren zu verstehen ist. Doch mit steigendem Abstraktionsgrad hingegen, werden die Grenzen zwischen Systemdokumentation (Rüping, 2013), Architekturdokumentation (Zörner, 2012), API-Dokumenta-tion, Referenzdokumentation, integrierter und separater Dokumentation (Ludewig/ Lichter, 2007) immer verschwommener. Vor allem die Inhalte, die sich hinter diesen Oberbegriffen verbergen, sind zumindest dem Namen nach verschieden. So zählen nach Rüping die Architekturdokumentation, die Designdokumentation, die Codekommentare, das Datenmodell und ein Glossar zur System-dokumentation (Rüping, 2013). Nach Ludewig und Lichter gehören zur Systemdokumentation die Anforderungsspezifikation, die Systemarchitektur, die Abnahmespezifikation, die Spezifikation der Systemtestfälle und der Programmcode (Ludewig/Lichter, 2007). Mayr zählt dagegen Dokumente zur Systemstruktur, zur externen Datenhaltung, zu den Komponenten, zur Installation, zum dynamischen Verhalten und zu den Begriffen zur Entwicklerdokumentation (Mayr, 2005).

Im Rahmen dieses Projekts soll daher nun systematisch untersucht werden, welche Informationen Entwickler wirklich zum Einstieg und zur Weiterentwicklung von Software benötigen und wie diese Informationen aufbereitet sein müssen, damit sie effizient und gezielt abgerufen werden können. Unserer Hypothese nach spielt dabei vor allem der Nutzungsanlass, also wann und mit welchem Ziel zur Dokumentation gegriffen wird, eine entscheidende Rolle für die Auswahl der Inhalte. Daher soll mithilfe von Interviews und Umfragen auch danach geforscht werden, in welchen Situationen und mit welchen Informationszielen Programmierer im Arbeitsalltag auf Dokumentation angewiesen sind.

Verwandte Arbeiten

Im Kontext von Entwicklerdokumentation kommt der Dokumentation von Programmierschnittstellen einer Software, den sogenannten APIs, eine besondere Bedeutung zu. Über APIs stellt eine Software anderen Softwareanwendungen Daten und Services zur Verfügung. Für die Akzeptanz und Nutzung von APIs ist eine gute Dokumentation der Methoden, über die eine API ihre Daten und Services anbietet, daher unerlässlich. Mehrere aktuelle Studien sind der Frage nachgegangen, welche Faktoren die Verständlichkeit und Benutzerfreundlichkeit von API-Dokumentation beeinflussen.
Jeong et al. (2009) untersuchten 2009 beispielsweise die Navigationspfade von Entwicklern bei der Nutzung der Online-Dokumentation für eine komplexe SAP-Schnittstelle. Aufgabe der Testpersonen war es, Services für eine im Testkatalog spezifizierte Aufgabe zu finden. Die Ergebnisse der Studie deuten darauf hin, dass nicht unbedingt die Programmierkenntnisse ausschlaggebend dafür sind, ob Dokumentation verstanden wird oder nicht. Vielmehr scheint das Hintergrundwissen zur eigentlichen Materie, sprich zu dem, was die Software macht, deren API man verstehen soll, eine Rolle zu spielen. Laut dieser Studie sind eine unübersichtliche Navigation und beispielsweise eine inkonsistente Gesamtgestaltung Barrieren, an denen selbst versierte Programmierer scheitern können. (Jeong et al., 2009)

Zum Thema „Nutzungsanlässe“ liefert die Studie von Brandt et al. (2009) relevante Ergebnisse. Im Rahmen eines kontrollierten Labortests wurde einer Gruppe von 20 Entwicklern die Aufgabe gestellt, innerhalb von 2,5 Stunden einen Prototyp für einen Online-Chatroom mit vorgegebenen Merkmalen zu bauen. Wie sich zeigte, verwendeten die Probanden 19% der Zeit darauf, im Internet nach aufgabenbezogener Information zu durchsuchen. Drei Ziele wurden bei der Informationssuche vorrangig verfolgt. Zum einen verfolgten die Probanden das Ziel zu lernen, d. h. neue Fähigkeiten zu erwerben. Weitere Ziele bestanden darin, bestehendes Wissen punktuell und aufgabenspezifisch zu erweitern sowie in Vergessenheit geratenes Wissen zu reaktivieren. (Brandt et al., 2009)

Diese Erkenntnisse scheinen zu bestätigen, dass die Inhalte von Entwicklerdokumentation zumindest hinsichtlich ihrer Aufbereitung, ausgehend vom Nutzungsanlass, ganz verschiedenen Kriterien genügen müssen.

Methodik

Anknüpfend an die Befunde aus der Forschungsliteratur sollen in der ersten Projektphase die Erwartungen von Softwareentwicklern an und ihre Erfahrung im Umgang mit Entwickler-dokumentation genauer in den Blick genommen werden. Im Zentrum steht dabei zum einen die Frage, wann und zu welchem Zweck Entwickler Dokumentation konsultieren. Zum anderen soll genauer untersucht werden, welche Wünsche und Erwartungen sie an die strukturelle, sprachliche und grafische Aufbereitung der Informationen haben. Im Rahmen der geplanten Studie kommen sowohl qualitative (Mayring, 2003) als auch quantitative Untersuchungsverfahren zum Einsatz. Über eine Serie von halbstrukturierten Interviews sollen zunächst weitere Informationen aus Sicht der Zielgruppe darüber gewonnen werden, wie Entwicklerdokumentation genutzt wird, welche Aufgaben damit typischerweise gelöst werden müssen, welche Information dafür benötigt und wo nach dieser Information gesucht wird. In einem zweiten Schritt sollen dann über eine umfangreichere Fragebogenuntersuchung zentrale Befunde aus der Interviewserie auf Generalisierbarkeit geprüft und bezüglich kausaler Zusammenhänge hin untersucht werden.

Darüber hinaus erhoffen wir uns weitere Informationen zum Thema Einarbeitung in eine neue Software über eine Longitudinalstudie. Hierbei werden mehrere neue Mitarbeiter in einem Unternehmen über einen längeren Zeitraum hinweg mehrmals nach ihren Erfahrungen bei der Einarbeitung befragt.

Ausblick

Basierend auf den qualitativen und quantitativen Ergebnissen der einzelnen Untersuchungen soll ein Optimierungsvorschlag entstehen, welcher sowohl Technische Redakteure als auch Softwareentwickler selbst dabei unterstützt, Softwareentwicklerdokumentation effizienter zu gestalten. Wir möchten praktikable Empfehlungen zu Inhalt, Struktur und äußerer Form geben. Diese Empfehlungen sollen exemplarisch umgesetzt und anschließend mit empirischen Testverfahren auf ihre Wirksamkeit hin untersucht werden. Die Optimierungsvorschläge sind vermutlich für Technische Redakteure leichter umsetzbar als für Entwickler. Doch wird in der Praxis die Entwickler-dokumentation zumeist von Programmierern selbst geschrieben. Diesen Umstand möchten wir bei der Ausarbeitung der Empfehlungen berücksichtigen. Peter Gruenbaum formulierte in einem Online-Artikel für das MSDN Magazine sehr treffend: „[most developers] love to code and hate to write“ (Gruenbaum, 2010), aber das muss ja nicht so bleiben.

Literatur