Examples are the best documentation

A Javadoc-esque API doc is the minimum requirement for a serious language/library. Examples and tutorials are nice too, but the API doc can be automatically generated in every serious language so not having it is just plain unacceptable.

Tutorials, articles and examples etc are fine too, they can be combined with the API doc like Java does. But that's gravy, on top. You don't have just gravy, it needs to be on top of something and that something is a proper API doc.

This isn't even a discussion in my mind, it's just the right way to do it. It's a solved problem. You optimize for power users not amateurs. 99% of the time when I look up docs what I need is a plain boring API doc, I only need examples in my first week.

Sure, but you can optimize for one without excluding the other. Adding examples _allows_ amateurs to gain experience and _become_ power user, and imposes near-zero cost on power users who can just skip a couple lines and get into the "real" API doc.

"No true Scotsman would want examples."

I'm far from an amateur and I want to see several concise examples in documentation. That doesn't mean that's all I want to see.

They're not the best. The best is thorough api docs. The rest is nice to have.

And I'm not no true scotsmaning, I'm just saying most devs are ass. I know, I see people with 20 years of experience on me write buggy trash code that I have to fix. I see people whine about the java docs as if they aren't some of the best damn docs available anywhere. Because they're ass and they can't properly use the tools they're given. They'd rather have examples and copy snippets from SO or have ChatGPT write it for them.

Any professional will appreciate proper documentation. It is literally impossible to create examples for every situation. Api docs, by their nature, cover all use cases because they simply describe what exists not how to use it. So for those of us with the knowledge and intelligence to actually just look at the parts and put them together on our own, ie professionals, API docs are king. Examples are useful sometime, API docs are useful all the time.

But of course if you don't even know the language well enough to read the documentation, you prefer examples.

If you don't even know the language well enough to read docs I'd say you're an amateur. And if you're one of those people who just chronically don't read docs you're definitely an amateur. I mean you may have a job and you may even build stuff that kind of works, but unless you're sitting down and looking closely at the details you're not doing things right. You can't be. Doing things right requires looking closely at the details.

And I know from experience that there's a vast number of employed amateurs who write nothing but legacy code.