6 ms·

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

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.

deleted 9y ago
[deleted]
jmfayard 9y ago
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 https://kapeli.com/dash
- microcolonel 9y ago
  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.
- rene_bg 9y ago
  Thanks for the link to Kapeli/Dash - looks like something that could really make everyday work easier!
- mjw1007 9y ago
  Note that the commonly-used GNU implementations of tar and find both have info documentation which is much better than the manpages.
- minusf 9y ago
  dash is web documentation kept offline with limited search added on top of it. it's basically a browser window...
  - dmitriid 9y ago
    Which already makes it orders of magnitudes better than man
    - vthriller 9y ago
      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.
wodenokoto 9y ago
Why should good documentation not be bundled with the product?
- pletnes 9y ago
  Sure. Cmake has a brief man page and a big bulky HTML manual.
Annatar 9y ago
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.

deleted 9y ago

[deleted]

jmfayard 9y ago

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 https://kapeli.com/dash

microcolonel 9y ago
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.
rene_bg 9y ago
Thanks for the link to Kapeli/Dash - looks like something that could really make everyday work easier!
mjw1007 9y ago
Note that the commonly-used GNU implementations of tar and find both have info documentation which is much better than the manpages.
minusf 9y ago
dash is web documentation kept offline with limited search added on top of it. it's basically a browser window...
- dmitriid 9y ago
  Which already makes it orders of magnitudes better than man
  - vthriller 9y ago
    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.

wodenokoto 9y ago

Why should good documentation not be bundled with the product?

pletnes 9y ago
Sure. Cmake has a brief man page and a big bulky HTML manual.

Annatar 9y ago

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.