Comment by bigstrat2003
5 days ago
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.
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.
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...
Checkout cheat.sh
I have this in a script: `curl cheat.sh/"$1"`
I'm always pleasantly surprised that many man pages do have examples. But, sure, they could be a lot more comprehensive.
I've developed the habit of checking the end of the page, because that's where the examples are, when there are any.
PHP documentation stands out with the comment section, like an integrated stack overflow, with examples and gotchas. It's what made PHP great.
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.
Totally agree but there is tldr for that.
I learned recently that tldr also has separate pages for subcommands.
tldr was created specifically to address this miscoming of the manpages. And it's recent enough to not ship with any distros.
It already exists - tldr. Use it side by side with man.
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
The GNU project choose to separate documentation into reference (man pages) and tutorials and prose (info). It works quite well and in my opinion info is also superior since it is an interactive hypertext system. So you can have cross-references, outlines, alternatives for different audiences, etc. .
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