Simplified and community-driven man pages

Re:Simplified and community-driven man pages by pletnes on Sunday November 26, 2017 @02:46AM (#15779887)

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 addition to man pages.

[ Parent | on HN ]

Re:Simplified and community-driven man pages by jmfayard on Sunday November 26, 2017 @03:41AM (#15780039)

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

[ Parent | on HN ]

Re:Simplified and community-driven man pages by microcolonel on Sunday November 26, 2017 @04:19AM (#15780128)

For what it's worth, find is truly awful, and tar is just a bit unconventional in terms of option parsing. These are stand-out failures of interface design, for which no documentation would be sufficient for all but the most regular of users.

[ Parent | on HN ]

Re:Simplified and community-driven man pages by mjw1007 on Sunday November 26, 2017 @05:55AM (#15780334)

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

[ Parent | on HN ]

Re:Simplified and community-driven man pages by minusf on Sunday November 26, 2017 @06:11AM (#15780373)

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

[ Parent | on HN ]

Re:Simplified and community-driven man pages by dmitriid on Sunday November 26, 2017 @11:46AM (#15781669)

Which already makes it orders of magnitudes better than man

[ Parent | on HN ]

Re:Simplified and community-driven man pages by vthriller on Monday November 27, 2017 @04:54AM (#15786123)

But why? You already can search through man pages with / key in your $PAGER (more/less/most/vimpager), and across pages with `man -k`/`man -K`, and I wouldn't really call proportional fonts as "orders of magnitude" better.

[ Parent | on HN ]

Re:Simplified and community-driven man pages by rene_bg on Sunday November 26, 2017 @05:53AM (#15780328)

Thanks for the link to Kapeli/Dash - looks like something that could really make everyday work easier!

[ Parent | on HN ]

Re:Simplified and community-driven man pages by Annatar on Monday November 27, 2017 @07:16AM (#15786738)

Good projects should have tutorials and complete references online in addition to man pages.

A well written manual page requires no additional tutorials, for they will be included in the text’s corpus.

Writing good documentation for one’s software is almost more important than writing the software itself; don’t force the user to have to run around the internet; be comprehensive in the manual.

[ Parent | on HN ]

Re:Simplified and community-driven man pages by wodenokoto on Sunday November 26, 2017 @03:03PM (#15782684)

Why should good documentation not be bundled with the product?

[ Parent | on HN ]

Re:Simplified and community-driven man pages by pletnes on Wednesday November 29, 2017 @08:50AM (#15806709)

Sure. Cmake has a brief man page and a big bulky HTML manual.

[ Parent | on HN ]