Live data from Hacker News

Ask HN: What is the best API documentation you have ever seen?

news.ycombinator.com

11–20 of 64 posts

Re: Ask HN: What is the best API documentation you have ever seen?

#11

Side note, how do I volunteer or work part time writing technical documentation? I feel like my writing skills and my ability to make code understandable and explicit to other readers would be a perfecy use for producing great documentation.

You can always pick a few projects on GitHub that have a less than ideal readme or set of docs and submit a bunch of PRs at once, I've done that before as a quick way to make myself feel like I'm contributing to the community whenever I don't have the motivation to push through on my own projects.

Re: Ask HN: What is the best API documentation you have ever seen?

#13
post #11

Side note, how do I volunteer or work part time writing technical documentation? I feel like my writing skills and my ability to make code understandable and explicit to other readers would be a perfecy use for producing great documentation.

You can always pick a few projects on GitHub that have a less than ideal readme or set of docs and submit a bunch of PRs at once, I've done that before as a quick way to make myself feel like I'm contributing to the community whenever I don't have the motivation to push through on my own projects.

Thanks so much!! It's a great way for me to help the projects I care about but don't have the skills to contribute .c .h files to haha

Re: Ask HN: What is the best API documentation you have ever seen?

#16
post #12

What are people's thoughts on Swagger?

I used to connect to REST (and SOAP/Graphql I guess, but that's not relevant) APIs for a living. Probably connected to about 200 or so. Swagger styled docs are only as good as the devs who write them. They have the potential to be pretty...but I couldn't care less about that.

Some of the worst docs I've ever seen used swagger. Some of the best I've seen used swagger, so the tool doesn't make the docs IMO.

I'd rather you email me a .txt file that's well organized and complete (including a damned baseURL, you heathens) than pretty swagger docs without substance.

Post reply on HN