Examples are the best documentation

They are not the “best.” They are helpful.

I am tired of rudimentary docs that only have examples.

Personally I am much more tired of lengthy troves of API docs that, while fully specifying the system, do nothing to specify how one is actually supposed to use it in practice, such as the general flow of the program itself, which functions are relevant to what overall operations, in what order certain functions should be called relative to others, how one should handle errors, etc.

If I at least have some examples to get me started, then I can go digging through other documentation (or even just the code) to figure how to do more advanced things... but being unable to even get started is a much bigger frustration IMO.

One time my company paid $5k for a commercial x264 license, and when we asked for some documentation on how to get started with encoding some video frames using their C API, they simply responded "the code is the documentation." With no real examples to go on (at the time in the 2000s there actually wasn't much available online at all), this set me back a good two weeks that I felt was completely unnecessary and completely turned me off to interacting with them at all for the future.

We ended up switching to a hardware solution that was much easier, faster, well-documented, and way friendlier people to talk to.

I agree that code is not documentation.

I agree that automatically generated API docs from code is nearly useless.

I agree that examples are important and useful.

But examples are not "the best documentation." Or I should say hyperbole is poor documentation of one's point of view.

Given the choice between massive, "complete" documentation with no examples and decent but incomplete docs with good examples, I’ll pick the second every time.

Why? Because if you don’t explain how to actually use something, all the fine-grained details are pointless.

Classic example: try looking up the Java docs around 2003–2005 to figure out how to display an image in a Swing application. Endless pages about Graphics2D and Image and double buffering and what not but not a single mention of the real solution:

Just put it in a JLabel.

FWIW that stuff was put in the Java tutorial (not sure if this is still the case today). The "Visual Index to the Swing Components"[0] (a copy i found online from ~2003) shows JLabel with an image and the docs even begin with "With the JLabel class, you can display unselectable text and images.".

[0] https://fizyka.umk.pl/~jacek/docs/javatutorial/uiswing/compo...