Requirements of API Documentation: A Case Study into Computer Vision Services

Cummaudo, Alex, Vasa, Venkata Rajesh, Grundy, John and Abdelrazek, Mohamed 2020, Requirements of API Documentation: A Case Study into Computer Vision Services, IEEE Transactions on Software Engineering, pp. 1-18, doi: 10.1109/TSE.2020.3047088.

Attached Files
Name Description MIMEType Size Downloads

Title Requirements of API Documentation: A Case Study into Computer Vision Services
Author(s) Cummaudo, AlexORCID iD for Cummaudo, Alex
Vasa, Venkata RajeshORCID iD for Vasa, Venkata Rajesh
Grundy, John
Abdelrazek, MohamedORCID iD for Abdelrazek, Mohamed
Journal name IEEE Transactions on Software Engineering
Start page 1
End page 18
Total pages 18
Publisher IEEE
Place of publication Piscataway, N.J.
Publication date 2020-12-24
ISSN 0098-5589
Keyword(s) Intelligent Web Services and Semantic Web
Code Documentation
Computer Vision
Summary Using cloud-based computer vision services is gaining traction, where developers access AI-powered components through familiar RESTful APIs, not needing to orchestrate large training and inference infrastructures or curate/label training datasets. However, while these APIs seem familiar to use, their non-deterministic run-time behaviour and evolution is not adequately communicated to developers. Therefore, improving these services' API documentation is paramount-more extensive documentation facilitates the development process of intelligent software. In a prior study, we extracted 34 API documentation artefacts from 21 seminal works, devising a taxonomy of five key requirements to produce quality API documentation. We extend this study in two ways. Firstly, by surveying 104 developers of varying experience to understand what API documentation artefacts are of most value to practitioners. Secondly, identifying which of these highly-valued artefacts are or are not well-documented through a case study in the emerging computer vision service domain. We identify: (i) several gaps in the software engineering literature, where aspects of API documentation understanding is/is not extensively investigated; and (ii) where industry vendors (in contrast) document artefacts to better serve their end-developers. We provide a set of recommendations to enhance intelligent software documentation for both vendors and the wider research community.
Notes In Press
Language eng
DOI 10.1109/TSE.2020.3047088
Indigenous content off
Field of Research 0803 Computer Software
0806 Information Systems
0906 Electrical and Electronic Engineering
HERDC Research category C1 Refereed article in a scholarly journal
Persistent URL

Connect to link resolver
Unless expressly stated otherwise, the copyright for items in DRO is owned by the author, with all rights reserved.

Version Filter Type
Citation counts: TR Web of Science Citation Count  Cited 0 times in TR Web of Science
Scopus Citation Count Cited 0 times in Scopus
Google Scholar Search Google Scholar
Access Statistics: 76 Abstract Views, 0 File Downloads  -  Detailed Statistics
Created: Thu, 21 Jan 2021, 13:14:17 EST

Every reasonable effort has been made to ensure that permission has been obtained for items included in DRO. If you believe that your rights have been infringed by this repository, please contact