21–30 of 64 posts
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.
Qt docs, python docs, cppreference, code synthesis odb
Python? I find the documentation to be confusing and difficult to search. Many of the arguments to standard functions are not explicitly documented nor do they have obvious enough names for me to guess what they mean. As I was learning Python over the past few years, I inevitably turned to blog posts and Stack Overflow for clearer examples and more explicit descriptions of optional parameters. I'd be curious to know…
What are people's thoughts on Swagger?
I haven't come across many swagger-based docs that I liked.
Having said that, I agree that it's a problem with the user, not the tool. Swagger is fine, you should just put some effort into using it well.
Stripe API docs. There have probably been many past threads about this.
Looks like they were partly generated, otherwise it would be impossible to keep everything consistent - especially with the many language examples. They also seem to generate an OpenApi Spec (or use this as a basis for generating the docs?): https://github.com/stripe/openapi
Lodash.js every single piece is explained with complete lucidity, and even if it weren't the examples are concise and illustrative.
It's a tiny thing that saves me a lot of time.
What are people's thoughts on Swagger?
One of the most important features of an API Doc is that it tells the complete truth and is always up to date. An OpenApi Spec therefore really "wants" to be auto-generated. There we've had mixed experiences, aswell. If the generator is not working as expected or missing a feature important to you, you're either limited or you take on generating it yourself.
I've used an approach a while ago, I was quite happy with, but it took some effort: Everything API related has one definitite source of truth. Out of that, generate the docs, example and specs you need. Also use this for validation. For Documentation, I've used a wiki. The generated docs or code snippets were generated as Templates, and could be embedded/transcluded in the documentation, which was otherwise hand-written. This provided a nice mix of written and generated content with full flexibility.
Auth0's is pretty damn good. Clear docs, inline sample code...Auth0 even inlines your credentials into the example code if you're logged in. [1] Auth0 - https://auth0.com/docs/api/authentication