Examples are the best documentation

Similarly, unix man pages desperately need examples. They are almost without fail written as an exhaustive reference for someone who already knows how to use the tool, which is a totally valid use case. But that means they're generally useless for someone trying to use a tool for the first time. Good documentation needs to have both.

Totally agree but there is tldr for that.

I learned recently that tldr also has separate pages for subcommands.

It already exists - tldr. Use it side by side with man.

tldr was created specifically to address this miscoming of the manpages. And it's recent enough to not ship with any distros.

I'm always pleasantly surprised that many man pages do have examples. But, sure, they could be a lot more comprehensive.

Checkout cheat.sh

I have this in a script: `curl cheat.sh/"$1"`

I've developed the habit of checking the end of the page, because that's where the examples are, when there are any.

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?!

This. I do not know how many people are disappointed at their initial contact with Unix/Linux because they hit a complicated man page while trying to use a command

I liked it when Stackoverflow did something similar.

https://stackoverflow.com/documentation

We have shut down Stack Overflow Documentation. Documentation was our attempt at improving existing reference materials by focusing on examples. The beta ran from July 21st, 2016 until August 8th, 2017. For more details on why we ended it, please see our post on meta. Thank you to everyone that participated. As always, the content contributed by our community is available under CC BY-SA.

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.

PHP documentation stands out with the comment section, like an integrated stack overflow, with examples and gotchas. It's what made PHP great.

I wholeheartedly agree, and would like to remind all man page authors that there’s even a conventional section named EXAMPLE. See man(1) for details. [0]

[0] https://www.man7.org/linux/man-pages/man1/man.1.html#DESCRIP...

The state of man pages in the GNU + Linux ecosystem is just atrocious in general. You can thank the GNU Project for that. In sane man pages that actually care about quality, examples are specified where appropriate: https://man.openbsd.org/apropos.1#EXAMPLES