Comment by inetknght
4 days ago
I haven't had that problem. I just code something up, and poke around to understand some of the terms that it's talking about. Then I start reading about error return codes, why them happen, what kinds of parameters actually mean, etc. No examples are usually needed as long as documentation is complete
The most frustrating things are things that are undocumented at all and only have examples. What the hell kind of shitty documentation is just examples with no idea what parameters could or shouldn't be?!
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.
> I'd have to read (in alphabetical order) the documentation for 6 different command flags.
You now you don't need to skim a man page like a physical directory? It's in a computer, just search for the flag you want to use.