3 ms·

> Bonus points for generating most/all of the endpoints. Swagger has solved that one for years now. In any case I think it's foolish to have multiple competing

> Bonus points for generating most/all of the endpoints. Swagger has solved that one for years now. In any case I think it's foolish to have multiple competing "sources of truth"... in the worst case you have stuff written on your website/Confluence/wiki, some manually written docs on Dockerhub, a README in the repository, an examples folder in the repository, Javadoc-based comments on classes and functions, Swagger docs (semi-)autogenerated from these, inline documentation in the code, years worth of shit on StackOverflow and finally whatever garbage ChatGPT made out of ingesting all of that. And (especially in the Javascript world) there's so much movement and breakage that all these "sources of truth" are outdated - especially StackOverflow and ChatGPT - which leaves you as the potential user of a library/API often enough with no other choice than to delve deep into the code, made even messier by the intricacies of build systems, bundlers and include/module systems (looking at you Maven/Gradle/Java Modules and webpack/rollup/npm/yarn/AMD/CommonJS/ESM). The worst nightmare is "examples" that clearly haven't been run in years, otherwise the example would have reflected a breaking API change whose commit is five years ago. That's a sure way of sending your users into rage fits. IMHO, there is only one way: your "examples" should be proper unit/integration/e2e tests (that way you can show your users how you intend for subscribers to use your interface, and you'll notice when your examples are broken because they are literally your tests!), and your documentation (no matter the format, be it HTML, Markdown or Swagger) should all be auto-generated from in-code Javadoc/whatever. Inline code should be reserved for stuff that's only needed to be known for someone intending to work on the actual library, to describe why you took a certain way of implementing a Thing (say, to work around some sort of deficiency) - think of the infamous "total hours wasted here" joke [1]. My to-go example, even if it is not perfect (the website is manually maintained, but the maintainers are doing a fucking good job at that!) is the Symfony PHP framework. With the exception of the security stack (that one is an utter, utter nightmare to keep up with), their documentation is excellent, legible, and easy to understand, and the examples they provide on usage are clear to the point. Even if you haven't worked with it for a year or two, it's so easy to get up to speed again. [1] https://nickyreinert.medium.com/ne-13-total-hours-wasted-here-42-175cb1d49728 https://nickyreinert.medium.com/ne-13-total-hours-wasted-her...

jillesvangurp 2y ago
> Swagger has solved that one for years now. I was referring to both the implementation and generating good/complete documentation strings for that, which is tedious and repetitive work. Obviously, I'm using openapi (aka. swagger); support for that is built into fastapi. That's one of the reasons I picked that. The tests are also generated but I screened them manually and iterated on them with chat gpt (also test this, what about that edge case, etc.). I know how to write good tests. But generating them is a way better use of my time than writing them manually. Especially spelling out all the permutations of what can go wrong and should be tested and asserting for that. AIs are better at that sort of thing. These are simple crud endpoint. I've written loads of them over the years. If you are still doing that manually, you are wasting time.

jillesvangurp 2y ago

> Swagger has solved that one for years now. I was referring to both the implementation and generating good/complete documentation strings for that, which is tedious and repetitive work. Obviously, I'm using openapi (aka. swagger); support for that is built into fastapi. That's one of the reasons I picked that. The tests are also generated but I screened them manually and iterated on them with chat gpt (also test this, what about that edge case, etc.). I know how to write good tests. But generating them is a way better use of my time than writing them manually. Especially spelling out all the permutations of what can go wrong and should be tested and asserting for that. AIs are better at that sort of thing. These are simple crud endpoint. I've written loads of them over the years. If you are still doing that manually, you are wasting time.