Sometimes, I just wanna remind myself how to use xargs for some command text replacement in a random one-liner on the terminal.
If I tried to do that with man... I'd have to read (in alphabetical order) the documentation for 6 different command flags. That's how far I'd go to read about the flag -- to actually use it, I'd have to experiment with the command flag until I figured out the actual syntax using my imagination.
Let's say instead that I am in a rush... so I'm skipping that time-consuming process and instead scrolling furhter down for some practical examples... one full page later I find a bunch! ... Except there's only 4 and none of them demonstrate what I need (the syntax is completely different). The docs wasted my time exactly when I most needed it NOT to do that. If I'd instead just googled "xargs replacement example", I would have gotten something I can copy/paste in seconds and could have gotten on with my life!
The moral of the story is this: Don't tell without showing. Don't show without telling. Do both if your goal is to be understood.
Once you have something working the way you like, make your own example and put it on a github repo named "today-i-learned". Then you can refer to it as your own documentation for yourself.
If I tried to do that with man... I'd have to read (in alphabetical order) the documentation for 6 different command flags. That's how far I'd go to read about the flag -- to actually use it, I'd have to experiment with the command flag until I figured out the actual syntax using my imagination.
Let's say instead that I am in a rush... so I'm skipping that time-consuming process and instead scrolling furhter down for some practical examples... one full page later I find a bunch! ... Except there's only 4 and none of them demonstrate what I need (the syntax is completely different). The docs wasted my time exactly when I most needed it NOT to do that. If I'd instead just googled "xargs replacement example", I would have gotten something I can copy/paste in seconds and could have gotten on with my life!
The moral of the story is this: Don't tell without showing. Don't show without telling. Do both if your goal is to be understood.