Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Simplified and community-driven man pages

tldr.sh

Post reply on HN
Print view View original

61–70 of 169 posts

Re: Simplified and community-driven man pages

#61

Post by mjw1007 »

jmfayard wrote: post #50
pletnes wrote: post #41

Earlier quoted context omitted.

I disagree. man pages are optimized for time spent. The cryptic synopsis at the top is enough if I’m checking a frequently used command. The examples are at the bottom for newbies, which need to spend some time reading anyway. man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addi…

A lot of us are "newbies" of "tar", "find", "[" and many others after years and years using *nix. According to the anti-usability mindset, this means that the users are wrong and ought to be changed, and not an hint that we should rethink how we write and consume documentation. Edit: the wording was angrier than it needed to be. A concrete example of a better documentation tool : https://kapeli.com/dash

Note that the commonly-used GNU implementations of tar and find both have info documentation which is much better than the manpages.

Re: Simplified and community-driven man pages

#62

Post by baddox »

dfabulich wrote: post #37
tnoerlcnt34 wrote: post #8

Earlier quoted context omitted.

Sure, but what usually happens is you sit down at a Unix command line for the first time and have no idea what to do. You ask someone (after seeing that `help` does nothing useful), and they tell you "use 'man' instead of 'help'". And you have no idea why, but you try it and it kind of helps and is better than nothing. You don't have any idea you should `read one of the many "Getting Started" or "Quick Guide" or "Beg…

I think this is how it used to be, but now people just Google their problems, and typically they get Stack Overflow as a result. Earlier this year, they announced that they have helped over one million developers to exit vim, for example. https://stackoverflow.blog/2017/05/23/stack-overflow-helping... In my experience, the top-rated SO answer is typically better than the man page, because it answers the specific ques…

I think I remember reading that a goal of StackOverflow was to essentially build comprehensive documentation of software in a question-answer format. That’s a neat idea. Most mature software has decent documentation in the form of a textbook or a technical manual, but it’s great to have everything documented in the form of “here’s an answer to every question you might have about this software.”

Re: Simplified and community-driven man pages

#63

Post by knolan »

dfabulich wrote: post #36
chao- wrote: post #30

I was lucky to first be introduced to man pages by someone who often just called them "manuals" and (to my best recollection) explained them by telling me "Manuals are to be read, top to bottom, contemplated, and maybe read again, before you act." Thus I was never under the delusion that man pages were, or should strive to be, How-To's of some sort. This TLDR tool definitely needs to exist, but in conjunction with ma…

The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations. Then comes a description, which is…

Even though I've fallen out of love with Matlab, its documentation is excellent. Brief description of the syntax for quick reference, a more detailed description, and finally detailed examples. Often there are references to the academic work behind the function and links to broader topics. Finally there's a bunch of related functions listed at the end which is great for discovering the vast array of Matlab's capabilities.

For example: https://uk.mathworks.com/help/symbolic/svd.html

Re: Simplified and community-driven man pages

#64

Post by PaulRobinson »

Hilariously, ITT are lots of comments saying that man is awful, in response to a pot about a "simplified and community-driven" alternative.

Breaking news: man pages are community-driven already. You can make them better in your distro of choice. The BSD projects are a little better IMHO at this than Linux because each project has a dedicated team trying to raise the bar and make their docs better than the next distro.

So don't make it simplified, don't hail "community-driven", just go and start making suggested changes with the rest of your favourite OS community!

Re: Simplified and community-driven man pages

#65

Post by JdeBP »

dfabulich wrote: post #37
tnoerlcnt34 wrote: post #8

Earlier quoted context omitted.

Sure, but what usually happens is you sit down at a Unix command line for the first time and have no idea what to do. You ask someone (after seeing that `help` does nothing useful), and they tell you "use 'man' instead of 'help'". And you have no idea why, but you try it and it kind of helps and is better than nothing. You don't have any idea you should `read one of the many "Getting Started" or "Quick Guide" or "Beg…

I think this is how it used to be, but now people just Google their problems, and typically they get Stack Overflow as a result. Earlier this year, they announced that they have helped over one million developers to exit vim, for example. https://stackoverflow.blog/2017/05/23/stack-overflow-helping... In my experience, the top-rated SO answer is typically better than the man page, because it answers the specific ques…

... or Wikipedia.

Interestingly, Stack Exchange answers are sometimes constructed by people using search engines to find phrase matches, sometimes with ridiculous results. (-:

* https://photo.stackexchange.com/questions/94238/who-or-what-...

That Stack Overflow web log entry is poorly researched, by the way. As I can attest from my own WWW site's statistics, there are reasons that a WWW site can have Ukraine at the top that have nothing to do with real people viewing relevant WWW pages, so conclusions such as

> It looks like developers in Ukraine, Turkey and Indonesia are getting stuck in Vim quite a bit:

are complete rubbish. One has to account for WWW browsers that pre-load pages, and WWW sites that feed stuff scraped from the likes of Wikipedia, Stack Exchange, my WWW site, and lots of others to WWW spiders: something that seems, from my statistics for this month so far, to be very popular for banking and pharmaceutical scam WWW sites in the Ukraine and the Russian Federation.

Here is how to exit emacs, by the way:

* http://jdebp.eu./Humour/exiting-emacs.html

Re: Simplified and community-driven man pages

#67

Post by mjw1007 »

IgorPartola wrote: post #26

Anyone ever get anything useful out of info pages (vs man pages)? I never quite got what their deal was.

As far as the content and organisation goes, they're basically doing everything right that manpages do wrong.

They separate tutorial and reference documentation, don't collapse under their own weight when they get large, and have a way to find the documentation for a particular short option.

The original standalone terminal reader was pretty poor, though. These days use pinfo or the html version if you're not an emacs user.

For a good example, compare `man sed` with `pinfo sed`.

Re: Simplified and community-driven man pages

#68

Post by detaro »

PaulRobinson wrote: post #64

Hilariously, ITT are lots of comments saying that man is awful, in response to a pot about a "simplified and community-driven" alternative. Breaking news: man pages are community-driven already. You can make them better in your distro of choice. The BSD projects are a little better IMHO at this than Linux because each project has a dedicated team trying to raise the bar and make their docs better than the next distro…

Have you successfully convinced any distro to deviate from the normal structure of a man page? If not, I don't believe your suggestion is very realistic.

Re: Simplified and community-driven man pages

#69

Post by minusf »

jmfayard wrote: post #50
pletnes wrote: post #41

Earlier quoted context omitted.

I disagree. man pages are optimized for time spent. The cryptic synopsis at the top is enough if I’m checking a frequently used command. The examples are at the bottom for newbies, which need to spend some time reading anyway. man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addi…

A lot of us are "newbies" of "tar", "find", "[" and many others after years and years using *nix. According to the anti-usability mindset, this means that the users are wrong and ought to be changed, and not an hint that we should rethink how we write and consume documentation. Edit: the wording was angrier than it needed to be. A concrete example of a better documentation tool : https://kapeli.com/dash

dash is web documentation kept offline with limited search added on top of it. it's basically a browser window...

Re: Simplified and community-driven man pages

#70

Post by ape4 »

menacingly wrote: post #13

I've always felt like it's a ding on my nerd credentials that I hate man pages. A lot of them feel deliberately opaque. 2-3 good examples are what joe blow is looking for when he types "man", and he rarely gets them.

Of course, many man pages have an EXAMPLES section. You can search for it with `/EXAMPLES` when viewing the man page. On my Linux box:

    zgrep EXAMPLE /usr/share/man/man1/* | wc -l
Gives

   897
Post reply on HN