Comment by happytoexplain
5 days ago
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.
[flagged]
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.
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`.
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.
>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.