Since it’s Sunday I wanted to slack a little. I decided to analyse State of API Report 2019 from DX perspective. I decided to continue with the documentation theme which was discussed yesterday too (“Natural language driven API documentation”).

Documentation is the 3rd most important factor

According to the respondents the most important factors of Great Developer eXperience are:

  1. Ease of use (over 60%)
  2. Responsiveness/performance (around 57%)
  3. Accurate and detailed documentation (around 50%)
  4. Service reliability (around 48%)
  5. Uptime/availability (around4 40%)
  6. Easy to maintain code (around 38%)

Documentation is top 3 thing for API consumers

One of the biggest areas of change from the 2016 State of API Report was the importance of ‘accurate and detailed documentation’. In 2016, documentation did not make the top five most important characteristics for API consumers, with less than 25% of participants selecting documentation as an important factor impacting their decision to adopt an API.

Code examples, code examples, code examples

Like former CEO of Microsoft once shouted on stage, the developers are shouting for examples in the API documentation. The top 5 most important things developers look for in API documentation:

  1. Examples (70%)
  2. Status and errors (51%)
  3. Authentication (50%)
  4. Error messages (49%)
  5. HTTP requests (44%)

API providers lag behind…

At the same time only 37% view documentation as a top priority for their organization. Only 35% of API providers feel that their organization’s API documentation is above average. Lack of time (question of priorities IMHO), resources and increasing speed of delivery were the top obstacles organizations face when implementing API documentation. A potential factor for why so many respondents felt that their API documentation was average or in need of improvement is due to the lack of investment in a formal API documentation process.

How is documentation created then?

Interestingly when the methods to create API docs was asked, 25% says they go “code-first” and it’s based on developer annotation. On the other end 43% say they use machine-readable spec files which might indicate “design-first” approach.

Design-First is getting traction. 69% of respondents use the OpenAPI Specification (OAS) in their API development. 2016 the percentage was 25%. It can be said that the adoption has been rapid and the OpenAPI Specification is the de facto standard for API design. 25% use OAS as Design-First approach only.

Of course there’s a middle way too. Do it code-first, but enable generation of spec file from it. Only 15% are investing in technical writers to help with documenting APIs.

To me all this sounds like companies are not taking into account the possibility to publish APIs which in the beginning are developed for internal use only. Remember the Bezos principle which required the opposite. In addition larger companies with plenty of people tend to put more effort in documentation since they need to make sure all in the company can use the APIs regardless of internal or public APIs.

Apparently the documentation process and tools need to evolve further. “Swagger view” is not good enough. We need easy to use, effective innovations in the area of documentation.


Some more to read from 100 Days DX