Hersteller von branchenspezifischer Standardsoftware stehen vor der Herausforderung, neben der Dokumentation für Installation, Betrieb und Bedienung der Software zusätzlich auch Software-Entwicklerdokumentation bereitzustellen, mit deren Hilfe Anwendungsentwickler kunden- und projektspezifische Softwareanpassungen und -erweiterungen vornehmen können. Entwicklerdokumentation soll Anwendungsentwickler in die Lage versetzen, diese Anpassungen und Erweiterungen in hoher Qualität und unter effizientem Ressourceneinsatz erfolgreich umzusetzen. Software-Entwicklerdokumentation ist dafür die primäre Wissensbasis.
Im Kontext von Entwicklerdokumentation kommt der Dokumentation von Programmierschnittstellen einer Software, den sogenannten APIs (Application Programming Interfaces), eine besondere Bedeutung zu. Über APIs stellt eine Softwareanwendung anderen Softwareanwendungen Daten und Funktionen zum Abruf und zur Verwaltung dieser Daten zur Verfügung. Bedingt durch die wachsende Rolle des Internets bei der Gestaltung von Geschäftsbeziehungen zwischen Unternehmen gewinnen vor allem Web-APIs mehr und mehr an Bedeutung. Die Einarbeitung in neue APIs gehört zu den alltäglichen Aufgaben von Software-Entwicklern. Für die Akzeptanz und Nutzung von APIs ist eine Dokumentation der Ressourcen, über die die API Daten und Services anbietet, unerlässlich. API-Dokumentation muss dabei nachweislich lerneffektiv sein, d. h. eine Einarbeitung und nachhaltiges Lernen in kürzest möglicher Zeit sicherstellen. Im Mittelpunkt des Projekts EXODOC standen daher die Fragen:
- Wie muss Entwicklerdokumentation für die Zielgruppe der Experten aufbereitet werden, damit sie den Lernprozess effektiv unterstützt?
- Welche Inhalte muss lerneffektive Entwicklerdokumentation anbieten und wie muss diese Information strukturell und gestalterisch dargeboten werden?
Ausgehend von diesen Fragestellungen hatte das Projekt zum Ziel
- die Informationsbedürfnisse und Lernstrategien von Software-Entwicklern abhängig von ihrem Expertisegrad durch quantitative und qualitative Untersuchungen zu ermitteln,
- darauf aufbauend konkrete Strategien und Umsetzungsempfehlungen für die inhaltliche, strukturelle und gestalterische Aufbereitung von Entwicklerdokumentation zu erarbeiten,
- diese Empfehlungen prototypisch zu implementieren und
- die Effektivität und Lernwirksamkeit der erarbeiteten Empfehlungen empirisch zu validieren.
Die Projektarbeit gliederte sich in drei Phasen mit jeweils unterschiedlichen thematischen Schwerpunkten. Ziel von Projektphase 1 war es, inhaltliche Erwartungen von Entwicklern an API-Dokumentation, Erfahrungen mit und wahrgenommene Mängel an Dokumentation sowie individuelle Lernstrategien von Entwicklern bei der Einarbeitung in eine neue API mit Hilfe von empirischen Methoden zu ermitteln und zu beschreiben. Entsprechend den unterschiedlichen Fragestellungen und Voraussetzungen kamen qualitative und quantitative Methoden zum Einsatz. Die gewählten Methoden orientierten sich dabei an klassischen Verfahren der Usability-Evaluation, wie z. B. dem teilstrukturierten Interview, der Methode des Lauten Denkens („Thinking-aloud“) und der Messung von Blickbewegungsverläufen („Eye Tracking“).
Auf Basis der in Phase 1 ermittelten Anforderungen und der Charakterisierung von Lernerwartungen und Lernstrategien wurden in Phase 2 konkrete Gestaltungsempfehlungen für API-Dokumentation abgeleitet. Die erarbeiteten Empfehlungen wurden in Form von Leitlinien und Heuristiken beschrieben. Die Heuristiken verweisen auf wesentliche inhaltliche und strukturelle Gestaltungsaspekte, können jedoch auf unterschiedliche Weise implementiert werden. Parallel zur Entwicklung der Heuristiken wurden daher Prototypen entwickelt, die konkrete Umsetzungsvarianten für die Heuristiken am Beispiel der Dokumentation für eine einfache REST-API demonstrieren.
Die in Phase 2 abgeleiteten Gestaltungsempfehlungen wurden in Phase 3 auf Basis der entstandenen Prototypen auf Lerneffektivität getestet. Zur Überprüfung der Lerneffektivität wurden Testreihen durchgeführt, die den Analyseschwerpunkt auf quantitative Daten bzw. auf qualitative Analysen legten. Zusätzlich wurde über eine Korpusstudie untersucht, in welchem Grad die in den Heuristiken formulierten Gestaltungsempfehlungen in aktuellen API-Dokumentationen bereits umgesetzt werden.
Auf Basis der Ergebnisse, die im Rahmen des EXODOC-Projekts ermittelt wurden, können Strategien zur Optimierung von API-Dokumentation abgeleitet werden. Technische Redakteure, Software-Entwickler und Informationsmanager werden durch die im Projekt entwickelten Leitlinien und Heuristiken dabei unterstützt, API-Dokumentationen und andere Lernressourcen gezielt an die Erwartungen und Bedürfnisse von API-Nutzern anzupassen und auf diese Weise die Benutzerfreundlichkeit, die Akzeptanz und damit letztlich den Markterfolg von APIs zu erhöhen.
Datenschutzhinweis
Wenn Sie unsere YouTube-Videos abspielen, werden Informationen über Ihre Nutzung von YouTube an den Betreiber in die USA übertragen und unter Umständen gespeichert.
Publikationen
Meng, M., Steinhardt, S., & Schubert (2018): API Documentation: What do Software Developers Want? Journal of Technical Writing and Communication, 48(3), 295–330.
https://doi.org/10.1177/0047281617721853
Steinhardt, S. & Meng, M. (2018): Verständlichkeit an der Schnittstelle. technische kommunikation, Ausgabe 1/18, 13-19.
Meng, M., Steinhardt, S., & Schubert, A. (2019). How Developers Use API Documentation: An Observation Study. Communication Design Quarterly, 7(2), 40-49,
https://doi.org/10.1145/3274995.3274999
Meng, M., Steinhardt, S., & Schubert, A. (2020). Optimizing API Documentation: Some Guidelines and Effects. In: Proceedings of the 38th ACM International Conference on Design of Communication (SIGDOC ’20), October 03-04, 2020, Denton, TX, USA. ACM, New York, NY, USA.
https://doi.org/10.1145/3380851.3416759