Ask HN: What are examples of good dev docs?

#1

Post by ibn-python » Wed, Aug 26, 2020, 11:58 PM UTC

Have an opportunity to provide input on my company's api documentation. What are some of your favorite examples of docs done well?

Re: Ask HN: What are examples of good dev docs?

#2

Post by michannne » Thu, Aug 27, 2020, 12:14 AM UTC

Tensorflow. Also the MSDN, specifically for .NET. I think having relevant examples explaining the impact of the arguments is more important than a dry explanation of the function itself.

Re: Ask HN: What are examples of good dev docs?

#3

Post by ldng » Thu, Aug 27, 2020, 1:35 AM UTC

Django is, IMHO, one of the best in both its content and structure.

Here is an enlightning talk about the structure : https://www.youtube.com/watch?v=azf6yzuJt54

Re: Ask HN: What are examples of good dev docs?

#4

Post by jdbowman » Mon, Aug 31, 2020, 9:47 AM UTC

What sort of API is it? Web-based (as in REST or GraphQL)? Or software libraries? Curious the language, in that case...

Re: Ask HN: What are examples of good dev docs?

#5

Post by ibn-python » Mon, Aug 31, 2020, 8:21 PM UTC

jdbowman wrote: post #4

What sort of API is it? Web-based (as in REST or GraphQL)? Or software libraries? Curious the language, in that case...

REST

Re: Ask HN: What are examples of good dev docs?

#6

Post by jdbowman » Mon, Aug 31, 2020, 11:18 PM UTC

ibn-python wrote: post #5

jdbowman wrote: post #4

What sort of API is it? Web-based (as in REST or GraphQL)? Or software libraries? Curious the language, in that case...

REST

A few that impress me: - Github: https://docs.github.com/en/rest/guides/getting-started-with-... - Twilio: https://www.twilio.com/docs/usage/api - Stripe: https://stripe.com/docs/api

You may also appreciate reading Swagger's tips: https://swagger.io/blog/api-documentation/best-practices-in-... and reading up on Swagger in general.