Examples are the best documentation

Examples are often crucially valuable, not just for beginners. Some of them can inject in five seconds an understanding equivalent to an hour of reading the very-objective docs and experimenting. I'm thinking of some git doc pages. But it applies just as well to single functions that are very simple conceptually, but hard to describe clearly and briefly and completely.

The developer has time for neither or both. Once the productivity barrier for one has been broken, the other is a tiny extra effort. In that case, they must provide both, except in the small minority of cases that are exceptionally self-describing, where one (usually docs) is sufficient.

Examples is for beginners. Beginners here refer to people that started to learn something, anything. But one you've got a conceptual understanding of the thing. You mostly need a full manual/reference.

Even as an "expert with several decades of experience" there are so many parts to a complex system that I still am a beginner in.

I’m not sure if that’s true.

The number of times I’ve opened FFmpegs man page must number in the hundreds. I think I’m a pretty good conceptually, but I can’t remember all the flags. IE that –s is frame size, while -fs is file size.

And while that man page does have some examples, these days I tend to ask an LLM (or if it’s going to be simple Google) for an example.

>Examples is for beginners.

No, not really, or I should say simple examples are for beginners.

Typically when I'm writing example pages I write it in

Simple example

Simple example

Simple example

Intermediate example

Intermediate example

Complex example.

Having complex examples can really help those that are looking at going beyond the basics.

That's why the recommended practice with shell usage is to write a script (or alias or function) and to use the long version of the flag in the script. Instead of having a complex invocation of ffmpeg, you'd have `flac2mp3 -q low file`.