I had an exchange with Abhinav Asthana (@a85), the Co-founder and CEO of Postman on Twitter today. He was tweeting about API documentation, and I chimed in with my support, about how we need to keep evolving our approach to delivering API documentation so that they speak to a diverse audience.
An API description created by experts is probably not the right way for building docs meant for beginners.
— Abhinav Asthana (@a85) March 7, 2016
While I think we have come along ways with the introduction of Swagger UI, making learning about APIs much more interactive, and hands on, I think its time to look at how we can further refine how we deploy API documentation for our users.
There is a lot going on with an API sometimes, and listing out all your endpoints, parameters, example requests, responses, and other elements can be overwhelming for new users who are just looking to learn the basics of an API, or possibly just get at s single resource, completing a specific action.
Swagger UI, and similar API definition driven documentation like Lucybot API Console, do well in providing a comprehensive set of documentation for a potentially wide variety of API docs, but we need to keep scratching. I'm not exactly sure what the answer here is, but I'd love to see much more simpler, embeddable, API documentation emerge. Solutions that allow API providers to display a small set of precise APIs, or possibly come up with some sort of slick user interface (UI), that delivers a simpler, more meaningful user experience (UX) that speaks to what a specific group of users is needing.
This is not a well-formed idea of mine, but is something I want to get out early. I'm seeing an increase in the number of new API documentation resources lately, and hopefully I can influence at least one or two of their road maps with my ideas. This is one reason I've broke out my API documentation research out of my API management research. I have numerous ideas for new types of smaller, more bite-size API docs, as well as more embeddable, and visual API docs as well--having a research project setup gives me a single repo to think about, and publish these ideas.
