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:
- Building Great API Docs by Greg Koberger (42 min video)
- The Four Layers to Great Documentation by Owen Kelly
- Five tips for improving your technical writing and documentation. by Tracy Osborn
Top comments (3)
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.