Stile von API-Dokumentationen anhand von Java und Python

Softwareentwicklung ohne den Einsatz von APIs ist für viele Programmierer heutzutage nicht mehr vorstellbar. Denn sie bieten vorgefertigte Lösungen an, die in die eigene Software eingebunden werden können. Das ist in der Regel viel bequemer und zeitsparender, als alles von Grund auf selber zu programmieren und bietet weitere Vorteile.

Genauso wie es eine Qual sein kann Programme mit schlechter Benutzerfreundlichkeit zu benutzen, kann eine schlechte Benutzerfreundlichkeit auch den Einsatz einer API erheblich erschweren.

Wie mehrere Studien herausgefunden haben, spielt die API-Usability eine große Rolle dabei, wie gut die API eingesetzt werden kann und dass sich eine schlechte API-Usability schlecht auf das Produkt auswirken kann, bei dessen Erstellung die API genutzt wurde.

Weitere Studien haben einen oft negativen Einfluss der API-Dokumentation auf die Benutzerfreundlichkeit einer API herausgefunden.

Das macht die Erforschung von \APIDokumentationen wichtig, denn sie können eine Verbesserung der API-Dokumentationen bewirken.

Vorgefertigte Designentscheidungen, die von Autoren von API-Dokumentationen dazu verwendet werden können je nach Szenario ihre Dokumentation zu entwerfen und zu schreiben, sind erstrebenswert.

Das übergeordnete Ziel dieser Masterarbeit ist es, diesem Ziel näher zu kommen. Dazu wurde die Hypothese überprüft, dass es unterschiedliche Dokumentationsstile gibt. Die Idee ist, dass unterschiedliche Dokumentationsstile verschiedene Vor- und Nachteile haben und entsprechend für unterschiedliche Szenarien besser oder schlechter geeignet sind.

Zu diesem Zweck wurden die von Maalej und Robillard vorgestellten[1] und von Wildermann erweiterten [2] Wissenstypen dazu verwendet Teile der Java- und der Python-API-Dokumentation zu typisieren. Das hat sich als eine gute Methode herausgestellt, um unterschiedliche Dokumentationsstile und Stileigenschaften von API-Dokumentationen zu erkennen. Dies war nämlich ein weiteres Ziel der Masterarbeit. Mit diesen Stileigenschaften kann nämlich untersucht werden, ob unterschiedliche API-Dokumentationen unterschiedliche Stile haben. Die Untersuchung ergab, dass es fünf Stileigenschaften gibt, die Stile von API-Dokumentationen beschreiben. Diese sind:

1. Aufbau und Form der Dokumentation
2. Beispielnutzung
3. Lokalität
4. Beziehungssichtbarkeit
5. Wissenstypzuordnung

Es besteht jedoch kein Anspruch auf eine Vollständigkeit. Denn es ist durchaus möglich, dass es noch weitere Stileigenschaften gibt. Die bisher entdeckten Stileigenschaften beziehen sich sowohl auf die Form und Präsentation von API-Dokumentationen, als auch auf den Inhalt. Außerdem werden zwei Dokumentationsstile vorgestellt, deren Aufspüren und Beschreibung ebenfalls ein gesetztes Ziel dieser Masterarbeit war: Der Referenz- und Buchstil. Die Dokumentationsstile konnten anhand der unterschiedlichen Ausprägungen der Stileigenschaften in der Java- und der Python-API-Dokumentation ermittelt werden.

Neben der Überprüfung der Hypothese, dass es unterschiedliche Stile von API-Dokumentationen gibt, der Identifizierung von Stileigenschaften und Dokumentationsstilen, sind die Erprobung und Entwicklung von Methoden, sowie ein Zusammentragen wichtiger Erkenntnisse für die Forschung in diesem Gebiet weitere Ergebnisse dieser Masterarbeit.

Auch wenn es noch offene Fragen gibt, sind die Ziele der Masterarbeit weitgehend erfüllt worden.

[1] W. Maalej and M. P. Robillard, Patterns of knowledge in api reference documentation, IEEE Transactions on Software Engineering, vol. 39, no. 9, pp. 1264-1282, 2013.

[2] S. Wildermann, Messung der Informationstypen-Häufigkeiten in der Python-Dokumentation, Bachelor's thesis, Freie Universität Berlin, 2014.