Using meaningful names to improve API-documentation

Description

Interaction between incorporated software-systems is often realized via application programming interfaces (APIs). The API-documentation explains how to use the API. If it misses important information, serious misunderstandings between the API’s consumer and provider can be the consequence.

I my talk I will show how meaningful names in the source-code can help finding gaps in the API-documentation. My findings base on my project-experiences and a cross-sectional study of a corpus of more than 186.000 web service-operations. I would like to share the 20 description-patterns for API-documentation I found so far. They provide detailed recommendations description of specific operations. The talk closes with a comparison of classical „swagger-like“ API-documentation with the presented approach.

  • Conference: Write the Docs EU
  • Year: 2016

About the speaker

Jan Christian Krause