Comment by harry8 | Hacker News Reader

Comment by harry8 | Hacker News Reader

I'm not following. The most useful thing on first read (and at other times) of man pages are the examples section. Frequently this section is pretty bare which is unfortunate. We should fix that. Yep with all of that.

npm install a thing with multiple clients. Um, huh? Where did that come from? At best now we have 2 competing man page systems, one for the "complete" information and one for the examples section? This is crazy, surely? You're not going to be able to stop using man pages! A replacement that can't be a replacement.

But sadly the examples themselves will probably have licensing problems to be able to be incorporated as documentation patches to the man pages - I hope I turn out to be wrong about that.

The meat of the project is a crowdsourced database of examples for each program. So naturally there can be multiple clients for that database implemented in various ways. That doesn't seem too complicated. You choose and install one of them. Kind of like how POSIX systems have dozens of pagers, text editors, etc. to choose from.

It also seems way less crazy to crowdsource good examples than get each individual program's maintainer to add examples to the official man page (which could take decades to actually get onto people's systems, if they're even accepted), and then still require people to scroll down to the examples section.

It's less crazy but more error prone. 3rd-party documentation has a tendency of being wrong and out of date quickly. It's not bad but it always needs to be taken with a grain of salt unless you really trust the maintainers of the docs.

That would be a very good point if this was documenting javascript frameworks, but I doubt the usages of "tar" and "find" change too often.

That's just a classic middlebrow dismissal comment.

This solution exists. Yours doesn't. This solution is also far more reasonable than yours. Your solution is to somehow land a manpage patch into every project while this is a single project that can be fleshed out by a single sufficiently motivated person.

Reply on news.ycombinator.com