Writing really good technical documentation and guides for APIs and SDKs is NOT easy. Any tips out there?

twitter logo Updated on ・1 min read

Any tips or sources on how-to writing really good documentation and guides for external APIs and SDKs?

Here are some resources I've found:

twitter logo DISCUSS (3)
markdown guide

I'm not as experienced as the resources you listed but I've seen my share of docs. One big recommendation I can make is to take time to write really good examples. There's nothing worse than a full detailed documentation with no examples. The documentation needs to be very pragmatic as well, so keep that in mind in the future!


Well I would suggest you look at the OpenAPI specification you can look at my experience in working with APIs and documentation in my recent article here Diving into OpenAPI


+1 for OpenAPI specification. We use swagger 2.0 UI for developer documentation. With a little bit of finagling, we were able to setup a contunious integration for documents. Any time openapi spec got changed, updated version of the API docs got generated and deployed automatically.

Example public facing api:

Example Swagger-UI where you could try the api directly

Setting up the dev document site is one of the topics in my list to write a detailed article about.

Classic DEV Post from Oct 27 '18

The State Of JavaScript

A deep-dive into the state of JavaScript

Brent Chow profile image
Co-founder at Svrf