4 ms·
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 ver
by happytoexplain 1y 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.
- skydhash 1y ago[flagged]
- bluGill 1y agoEven as an "expert with several decades of experience" there are so many parts to a complex system that I still am a beginner in.
- nmcfarl 1y agoI’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.
- skydhash 1y agoThat'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`.
- pixl97 1y ago>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.