Hacker News Reader

Comment by dvh | Hacker News Reader

One thing I hate about man pages is that there are not enough examples. Sometimes feature is explained on five pages while simple one line example would explained it instantly. And at the end there should be 2-3 pages of examples at least, maybe even more.

View on HN

If you’re using a GNU system now you might be surprised by the quality of the BSD man pages, and documentation in general. Concise but still comprehensive, and plenty of examples. The tools (like man) aren’t really the problem here, the documentation itself is. (But it helps that the BSD folks show a bit more restraint wrt adding command line options.)

I have just compared the man pages for Linux and FreeBSD, but the result is not really clear:

Example provided on the FreeBSD man page of cut.

Examples provided on the Linux man page of xargs.

More examples provided on the Linux man page of find.

I find the cut man page (looking at the OpenBSD one) very clear. It's just 62 lines (fits on a screen), has only 5 flags and the 2 examples clearly show how the tool is used.

The xargs man page is ought to have some examples, I agree.

The find manual is lengthy (as it has a bunch of options) but not excessively so and it also has a good bunch of examples.

Edit: it also helps to be familiar with the pager, like using the search feature (hit / , n, n, Shift+n, ...) and the jump keys (G and g).

Not enough examples is only in GNU/Linux; the BSD’s and illumos-based operating systems have plenty of examples. Especially illumos, since they enforce a rule that no component may be integrated without a comprehensive manual page and since they come from Solaris, most of the documentation was written by a dedicated department of professional technical writers working with the engineers to document their work in a systematic fashion.

Those who can, do

Those who can't, teach

Those who can't teach, write

Those who can't write, write man pages

This is a pet peeve of mine. Teachers are not somehow inferior to those who do. It's a completely different skill set that actually helps you "do" better.

Exactly. In sport we respect coaches for their particular skills. But somehow teachers get joked about.

Sure we respect coaches, but we also still in every sport pay them significantly less than the pros they ostensibly lead. I personally value both coaches and teachers but it's very clear that we as a people have decided that ability to do is more valuable than the ability to teach others.

H.L. Mencken had a strong antipathy to teachers, and maths specifically.

Rather a disappointment.

And those who believe in this aphorism have never did, taught or written :)

honestly, not having a man page would be better than half of the man pages out there

Having benefited tremendously from manpages I believe they're absolutely worth existing, whatever manpage seemed insufficient to you.

Those who can, do. Those who can't, become product managers.

I find that this is something openBSD gets /really/ right. In general the man pages in BSD are phenomenal.

What happened to ‘info’ pages. I hated it, but wasn’t that supposed to address these kinds of issues with examples?

Info pages are still there.

    $ info grep

Info is much better than man, but keep in mind it's only covering gnu coreutils (which isn't a bad thing!)

Why is info better than man?

The man page for gcc goes on and on. Try it.

The info for gcc is a printed book, which is also accessible in the shell as hypertext (which predates html).

Better search and better organization of the document (TOC, index search, etc.). And reading/searching Info manuals is a lot more convenient in Emacs Info-mode.

Huh? grep is not part of coreutils.

I know this is late but you are right. For some reason I thought info was only fore coreutils, but it seems I was wrong. I only ever used it for coreutils, but hey, thats good news to me!

perldoc begins with examples by convention. No need to /EXA

See e.g. https://metacpan.org/pod/release/PHRED/Archive-Zip-1.62/lib/...

Sounds like you want bro pages

http://bropages.org/

I don't think the use case is the same. um is for saving and viewing personal notes about usage, bropages is a common set of examples submitted by the wider community.

This other response says it better: https://news.ycombinator.com/item?id=17801788

that's what bro does by default; you only push an example to the community explicitly.

Man pages are a community project. Send patches!

While this is laudable, how many GNU projects, especially, don't use an archaic development/contribution process? I don't want to have to register on a mailing list and prepare patches.

This is an honest question. Friction and barriers to entry reduce contributions.

More importantly, many (most?) GNU projects don't care about man pages:

https://www.gnu.org/prep/standards/html_node/Man-Pages.html

This encapsulates one of my biggest gripes with Linux. A lack of appreciation for adequate/good documentation.

> The time you spend on the man page is time taken away from more useful work.

Making sure your users know how your program works, how to use it and what it's capable of seems incredibly important and useful to me.

If it weren't for Arch Linux's fantastic focus on documenting everything to do with Linux, I wouldn't be using Linux at all.

GNU deprecates man pages in favor of texinfo, not no documentation at all.

https://www.gnu.org/prep/standards/html_node/Documentation.h...

That page is specific to man pages, not to documentation in general.

See https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm...

I second this, there's so much wasted work, and because that old contribution process there's no guarantee that even an absolutely fantastic patch, like a better man page for example. Will ever see the light of day.

I've tried in the past, it doesn't work out (not man pages, but I was fixing a bug and yeah, three, four submissions was enough for me to quit trying)

It's not hard, just suck it up and register for the ML, and prepare the patches. People are irrationally scared of this process. There are plentiful guides.

I don’t think being afraid of the process is the problem. It’s more about how unnecessarily manual the process is paired with the possibility of your patch’s email thread getting buried never to be seen again or worse, its reviewer abandoning it halfway through the review process with no easy way for someone else to pick it up.

That’s not to say that Github pull requests and the like are perfect (far from it) but it’s undeniable that they smooth the process quite considerably and make contribution far more accessible.

People are busy. If you want your patch considered, you should be bumping it and reaching out to people who can merge it. Man page improvements are generally a shoe-in, just get someone to pay attention to it for a few minutes and it'll get in.

The process you're describing in this comment is exactly the outdated approach people are saying they don't want to do.

It's not like this isn't a problem for GitHub, either. Pull requests go ignored, too.

It's not always that it's hard, rather it can be demoralizing to have the same experience that @S-E-P did [a sibling comment to yours] where you _do_ expend the energy and then patches sit unactioned for months or years

Your patches are your responsibility. Bump them, reach out to maintainers directly, etc. Manual improvements are easy to review once you can get someone to.

Or I could just do what 99% of devs do, not give a crap and try StackOverflow/blogs to find an answer... That was my whole point, higher friction => much fewer contributions.

Higher friction => higher quality contributions.

But also fewer contributions, I reckon. If someone wants to contribute something big, they'll jump through all the hoops. But if all one wants is to contribute another example to a man page, I'd wager they're more easily discouraged by an arcane setup process. GitHub solves a lot of this friction by having:

  1. One account for manifesting your chosen identity, which you likely already have.
  2. One common way of getting the source code and sending diffs/patches (read: PRs).

The workflow is quite similar, in the abstract. But GitHub and friends solve important pain points.

1. One account for manifesting your chosen identity, which you likely already have.

You also have an email address, so. You need an email address to get a GitHub account, so technically it's harder to set up GitHub.

2. One common way of getting the source code and sending diffs/patches (read: PRs).

This is built into git. Don't need GitHub for either.

It looks like you think that older approaches to open-source collaboration (like many of the GNU projects are using) are more or less as user-friendly as GitHub. I don't have the data to prove that they aren't, just an intuition.

Perhaps the last argument I have is that I've heard a number of times about moving a project to GitHub (for example: the Go language or Vim the editor), but decidedly less often one hears of projects moving away from GitHub towards older forms (such as the wonderfully documented https://gcc.gnu.org/contribute.html). Despite the great documentation, I'm somehow not drawn to hacking on it to fix a small glitch, due to the overhead that entails. Mind, some of that overhead would be incurred just once, as it is general to the mailing list approach to collaboration. That, I believe, is another advantage of a project being on GitHub: for almost all projects there's a standard way of sending your patch: make a pull request.

About your counterpoints:

1. True. I was thinking of the bug trackers many mailing-list oriented projects have, which often require creating accounts just to file a bug. 2. I was more referring to things like (1) where to find the clone URL and (2) how to send a patch (the make a PR button is always the same).

Removing friction (even small frictions) will enable fishing for the long tail of small fixes. On the other side, I do not believe large contributions are greatly affected by the differences between these systems.

Attempting to read nix man pages, always felt like I was alone in learning best from examples. Documentation in any form without examples is always difficult for me to sort through.

tldr tries to fix that: https://tldr.sh

Ever since I have discovered tldr i've been using man pages less and less.

When viewing man pages, you are using less by default.

lrf, guvf vf n cha

Also a big fan of tldr :) But love the idea of writing my own.

Reply on news.ycombinator.com