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 you like about the Python documentation because my experience has probably been different than yours.
I feel similarly about Python. I never really had to interact with it beyond using it as a calculator on the command line until a project I was a part of earlier in the year had a utility Python script introduced and I needed to hack on it to make desired changes. Then, more recently, I started using BeautifulSoup[0] for personal scraping. Of course it feels more trivial now (and now I wish I documented my frustrations so I could be more specific and perhaps help out other Python learners in the future), but it does take a while to adjust to Pythonic code where everyone is using cultural conventions like _foo and __foo and you wonder what the hell __foo__ is[1].
More on-topic, searching is a major weakness of Python's docs. What's that? Python just got multi-line strings allowing embedded expressions? They're called f-strings? Let me go read about them[2]. I can't link it, but even using Startpage the immediate results are a post from RealPython and PEP498 and while both are great, they aren't terse enough to be frequently referenced. If you search for "formatted string literal"[3] in the docs it takes 10 results before you reach something explicitly talking about them. And then you need to follow the links a couple times to reach https://docs.python.org/3/reference/lexical_analysis.html#f-... (notice it is anchored as "f-strings" which was the first term we searched for).
While the Python docs, when I've found them, have been adequate for me so far -- although I still check up on how others do the things I want to do -- I'm partial to docs such as MDN that cover parameters and return value in one take for reference with more in-depth information as you scroll down, if needed[4].
I'm very impressed by those docs. Anyone has insights how they were made?
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
Stripe started really really well with its developer, library and documentation support. In fact I think that’s a very large part of their initial success.
At some point they lost that focus and dropped the ball. For example for a very long time they had no direct support for reactjs even when it was hugely popular, instead you had to go find some third party library which is a terrible thing to have to do for implementation of payment code.
Maybe they’re improved and started supporting actively the technologies developers are using.
I think Stripe offers a great product, but I still don’t think they have direct support for react-native, relying instead on a third-party library which isn’t very well documented, and only implements portions of the stripe API.
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.
I emailed one of the only public and most likely guessable aliases at your domain, please let me know if you would prefer for us to chat in a more cryptographically secure manner.
A small detail, but Lodash is also globally available on their doc page. So if you see a piece of documentation and want to experiment with it, you just hit Ctrl-Shift-I and start typing.
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.
I feel like people want swagger to generate good docs for them, so they jam all the auto-gen annotations and what not into their code base and pump out the default generated docs and more or less leave it at that. And it's awful. The code base swells up with annotations and the docs are permanently neglected.
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.
OpenApi 3.0 is quite nice to work with. Its verbose to write by hand, though and you also need to know JSONSchema. With the Swagger UI we've had some mixed experiences. Not everything you can express in the Spec is displayed very well. But for developers, it's a nice playground / entrypoint for backend projects. We wouldn't want to miss that. (You also get this for GraphQL with the GraphQL Playground)
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.
Not API, but Spark Java (http://sparkjava.com/documentation#getting-started) has one of the best Java framework documentation I've ever seen. Fairly concise + it has almost everything you need to build proper Web application using Java
I thought the same about those until I tried to follow the examples. First in ruby and then in Vue, neither worked without a lot of hacking/changes. Really cool idea though to put the credentials in the examples.
Stripe is probably the best but I think Twilio is a close second. For both the page designs are easy to read, there are clear examples (some are even interactive), and the sites are easy to navigate.
Twilio's API and SDK references vary from practically non-existent to completely unusable. I often have to resort to reading their SDK code to figure out what methods to use.
Huh. I've always found them to be the absolute worst docs I've ever seen. Any simple Google search will bring me to a page full of vaguely connected things with no particular headdings or way to quickly get the info I'm looking for.
I really like the Lua reference manual. All on a single page (e.g. https://www.lua.org/manual/5.3/manual.html), covers the complete syntax/semantic of the language, a few concepts as well as its Lua and C embedding APIs. All without bells and whistles. It surely helps that it's a relatively easy language. While I learned Lua, I basically never had to look anywhere else for information. I guess that's what a good documentation is supposed to aim for.
EVRYTHNG Platform docs are extremely thorough and versatile. There're also lots of guides and examples covering how to work with their platform. Taking into account complexity and amount of abstractions, those are one of the best docs i've ever read.
63 comments
[ 2.4 ms ] story [ 107 ms ] threadI'd be curious to know what you like about the Python documentation because my experience has probably been different than yours.
More on-topic, searching is a major weakness of Python's docs. What's that? Python just got multi-line strings allowing embedded expressions? They're called f-strings? Let me go read about them[2]. I can't link it, but even using Startpage the immediate results are a post from RealPython and PEP498 and while both are great, they aren't terse enough to be frequently referenced. If you search for "formatted string literal"[3] in the docs it takes 10 results before you reach something explicitly talking about them. And then you need to follow the links a couple times to reach https://docs.python.org/3/reference/lexical_analysis.html#f-... (notice it is anchored as "f-strings" which was the first term we searched for).
While the Python docs, when I've found them, have been adequate for me so far -- although I still check up on how others do the things I want to do -- I'm partial to docs such as MDN that cover parameters and return value in one take for reference with more in-depth information as you scroll down, if needed[4].
[0]: https://www.crummy.com/software/BeautifulSoup/
[1]: Here's a start for reading. https://stackoverflow.com/questions/8689964/why-do-some-func...
[2]: https://docs.python.org/3/search.html?q=f-string
[3]: https://docs.python.org/3/search.html?q=formatted+string+lit...
[4]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...
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
At some point they lost that focus and dropped the ball. For example for a very long time they had no direct support for reactjs even when it was hugely popular, instead you had to go find some third party library which is a terrible thing to have to do for implementation of payment code.
Maybe they’re improved and started supporting actively the technologies developers are using.
There have been. The following is a good search to use to find other discussions.
https://hn.algolia.com/?query=&sort=byPopularity&prefix&page...
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.
Thanks!
(Your profile email isn’t public!)
It's a tiny thing that saves me a lot of time.
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.
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.
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.
[1] Auth0 - https://auth0.com/docs/api/authentication
https://www.bytecellar.com/2004/06/15/apples_pascal_s/
And thanks for giving me a name for them, too.
There are BNF to railroad diagram generators (they take a "grammar file", often BNF, and output a railroad diagram).
https://www.postgresql.org/docs/10/static/index.html