AI is just another tool. A pretty good one. And there is a skill to using it efficiently. If you ask it dumb questions, you will get dumb answers. Garbage in, garbage out. I am a software developer and I hire devs as well. If somebody is ignorant of AI or refuses to use it, that is hard pass for me. It is not all that different from an accountant not wanting to use computers. Sure, you could still do some work. But,…
Exactly. I expect people to know, be proficient with, and use all relevant tools available to them. Including AI; but not just AI. There are a lot of people trying to argue why they don't want/need to use certain tools. A job interview would be the wrong place to have that argument. A good, open interview question these days would be asking candidates how they are using AI in their work and what challenges they are f…
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-her...