Better API documentation with AI

Quod AI co-founder Herve Roussel was invited to speak at apidays Live Singapore’s virtual conference this past August. Today, we share his insights from his talk “Your API Documentation powered by AI”.

Better API documentation with AI

Today, software is released and moves more quickly, and architectures have become more complex than ever before. To meet the accelerating pace imposed on them, developers expect much more from their API documentation. Artificial intelligence is proving to be key to meeting their ever-growing needs.

Herve Roussel was invited to speak at apidays Live Singapore’s virtual conference in August. In this article, we share the key insights from his talk “Your API Documentation powered by AI”.


Is good API quality a problem for your organisation? You’re not alone.

According to Smartbear’s State of API 2019 Report, the greatest factors impeding API quality are the increasing demands on the speed of delivery, the lack of time and resources due to current workload, and the lack of tools and technologies. These factors are shown to affect organisations of all sizes, regardless of the number of employees.

In the same report, when queried on the top three characteristics needed in an API, the three most common responses from API consumers and developers are ease of use, performance, and accurate or detailed documentation. In particular, the “ease of use” and “detailed documentation” answers were both selected almost twice as often as compared to the report three years prior. Additionally, most developers would also assert that accurate documentation would in turn contribute to ease of use.


What is the state of API documentation now?

Only 33% of API providers feel that their API documentation is above average, while 35% of API providers would describe their current API documentation as “poor” or “needs improvement”. Unsurprisingly, of the respondents that felt their API documentation is “good” or “very good”, more than half responded that documentation is a top priority for them.


What makes documentation “good”?

In general, good API documentation would be able to answer the following two questions:

  1. What can I do?
  2. How can I do it?

Firstly, good documentation should enhance discoverability within the code. Examples of good discoverability include ease of searching and finding, quickstart guides and endpoint definitions.

Next, it should also be easy and simple to use. Some characteristics that it would have are it being interactive, readable and consumable, and should also display either code snippets or example responses.

Finally, good documentation does not have to be complex. A good example would be stripe API’s documentation, where both the discoverability and the useability appear all on the same page.


How can AI make documentation better?

QuodAI has developed AI models that are able to help developers address both characteristics of good documentation. These models break down an organisation’s repository into its functional segments or snippets of code.

Next, using deep learning and natural language processing, AI is able to organise the code snippets by their functions and characteristics, and will automatically generate descriptions and tags for each snippet. These descriptions make the code easily readable and understood, and are also example responses that developers can draw on and use.

Lastly, the results of the AI model are presented as a search engine, where developers are able to search through the snippets of code, will be shown other snippets of code that are related to what was searched, and are able to group similar pages of code together in a collection for easier navigation.


Watch the full recording on apidays LIVE Singapore 2020

Featured posts