Another API the Docs virtual meetup took place last night, the third one of the second season. Michael Meng, Lorna Mitchell, and Patrick Hammond shared their thoughts on API documentation. As for the first and second meetup in the season, I’ll provide a little personal recap.

Michael Meng, a professor at Merseburg university, talked about research-backed ways to improve API documentation. The key questions are, which information should you present, and how? Previous research indicated different strategies in the way developers access documentation. There is the opportunistic, or exploratory, strategy, and the systematic strategy where developers try to gain a broad understanding first (a pragmatic approach combines both). In general, they access documentation in a task-oriented manner, focused on code examples (which backs up nicely what Milecia McGregor said about code samples at a previous meetup). It’s also vital to explain underlying concepts, but best integrate them into use cases as developers often don’t read separate concept docs. Michael’s team created guidelines for enabling efficient access and facilitating initial entry into the API and then rewrote documentation for an existing API based on those guidelines. They invited 22 developers and asked them to complete a task. Half of the group got the original documentation. The other half got the optimized version. What I found interesting is that the group who got the optimized documentation performed more accurately, but only slightly faster. However, they did spend more time in the documentation, which indicates that good documentation motivates developers to understand first and then act where they would otherwise spend time in trial-and-error experimentation. Michael was careful about his study’s replicability and said there needs to be more research to disentangle different optimizations. The paper is available as open-access research.

Lorna Mitchell started her talk by quoting the Postman State of the API report, which maintains that the top issue with APIs is documentation, just as the research Michael mentioned. She said: “It’s not an API if it doesn’t have (reference) documentation.” I also liked how she compared various improvements to API documentation with a restaurant menu. Even though a customer doesn’t order everything at once, every menu item improves the whole thing. She mentioned a list of those improvements, with “Getting Started Content” being the first, reminding us that “every API is someone’s first”. Hence, you shouldn’t be afraid to go overboard in the documentation and make sure to link additional resources. It seems obvious, but also Adam DuVander said many companies don’t have a “Getting Started” guide. Examples are “worth many words”, and OpenAPI helps. Lorna also explained their docs-as-code setup where they use separate standalone files included in the docs through custom wiring (again, the approach that Milecia suggested as well). Their code snippets are parts of longer files with full examples stored on GitHub.

Lorna mentioned another type of content: “HowTo: X with Y” guides, where X is a common task, and Y is a tech stack. They can be blog-type content but also part of documentation and should be end-to-end guides. If developers use them and some read nothing else, they should be fine. Along with those go demo apps, where you should mix up different tech stacks. I was happy she mentioned these two types of content as I enjoy creating those for my clients. Finally, she included troubleshooting guides (which people can find searching for error messages) and recommendations of related tools (that the company uses internally but can also help API consumers). One of these tools is Postman, and Lorna added that releasing Postman collections provides additional value, even if Postman can import OpenAPI. Also, SDKs are helpful, even if they are just a thin layer over the API. However, only ship what you can support! Lorna recently wrote an article on SDKs. Also, check out my summary of an interview with Lorna if you’re looking for more nuggets of API-related wisdom from her.

The third talk was by Patrick Hammond, who explained the docs-as-code/DocOps approach at Adyen. Sadly I had to leave halfway through the presentation for another meeting, so, unfortunately, I can’t provide you a summary this time.