6 ms·

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

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 fine, and then a list of options in alphabetical order which is almost always the least useful ordering. Categorize the parameters. Juxtapose confusingly similar options. And only then do we get any examples, if any. The examples should have come first, in the synopsis. There's nothing inherently wrong with man pages, but nobody has to follow this tradition. Put real examples in your synopsis and manually sort your options; you'll have a man page that's 20x better than most.

pletnes 9y ago
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.
microcolonel 9y ago
> not even as a reference How are you supposed to write reference documentation without a section for describing the options which can be referred to by option name? > The examples should have come first, in the synopsis. Type with me: / E X A <return>. If anything, perhaps the first manual a man user should read is the manual for their default pager, usually LESS(1). There are good and bad manpages, but I don't see how the format is truly deficient. Some very complex commands have separate sections for the most and least common options (or groups of related options, if there are subcommands or similar).
unixhero 9y ago
I agree. An an author of several command line tools I would never document it's usage in the way the classical man pages are structured. They are in times of dire need, frankly, unhelpful. I ALWAYS have to Google it, since the man page gave me nothing.
knolan 9y ago
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 https://uk.mathworks.com/help/symbolic/svd.html
jmfayard 9y ago
Man is like javadocs: useless unless you already know what you are doing, and then usually a wordy paraphrase of the method signature :( Even as a reference manual, man is bad though. If I'm looking for option "-e" of the test command, why can't I do $ man test -e -e file True if file exists (regardless of type). That seems more efficient, more unix-friendly and not too much to ask. I get this is an historical tool that only cares about displaying the output of nroff. We would need a new tool with more empathy ($ woman? )
- kleiba 9y ago
  De gustibus non est disputandum. I've found javadocs enormously helpful when I was learning Java 20 years ago. But then again, I also like man pages and use them a lot. If I'm looking for option "-e" of the test command, here's what I would do: $ man test and then "/-e". Searching within a document is a commonly required skill in so many situations that I don't even think twice when applying it in man pages. Of course, you could also just define a bash function for the functionality you're after like so: mano() { man "$1" | grep -A1 -- "$2" } and then do $ mano test -e or something along those lines.
  - jmfayard 9y ago
    That's full text search, not having directly the argument definition. If you search "-l" in "man ls", it will be only your 8th occurence.
    - kleiba 9y ago
      Sure, you're right, it's not the same thing. I just gave a simple example of something that's close, but I'm not even using a bash function like that myself. If I did, though, I guess the 8th occurrence wouldn't be so bad in my book, since the results can be scanned rather quickly. You could always make your function more clever, e.g.: function mano() { man "$1" | grep -A1 -- "$2\\b" } or function mano() { man "$1" | grep -A1 -- "$2 " } but most probably, you will still run into edge cases that won't work properly. For instance, only one of the two versions above still works with "test -e".
justin66 9y ago
> The examples should have come first, in the synopsis. That is just a terrible idea. First, if what you're putting in the synopsis is not "a brief summary or general survey of something" then the section is misnamed or the content does not belong there. Examples don't belong there. Second, and more importantly, plenty of commands can do enough damage that people ought to read up on what they do before receiving an example. You're giving someone a false sense of confidence if you throw an example at them first thing. That's appropriate enough in some contexts, but not in official documentation for software tools. > The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. The problems you go on to list have nothing to do with the structure, and everything to do with the content contained within that structure. > No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. Since "documentation experts" write documentation this way, it's hard to imagine why you'd assert this.
- xtiansimon 9y ago
  I share your reactions, with the exception that examples first or last seems irrelevant when using a man page—Sometimes it’s better first because you simply need a reminder how to use the command, and other times you need to read more of the description to catch the warnings before you use the command for the first or infrequent time. But if you follow the General best practice to read the whole of some documentation before you use a command, then this too seems irrelevant. That said, if you’re writing, reviewing, and editing documentation, the traditional structure is hierarchical and consistent—-which is good.
Annatar 9y ago
and maybe Examples at the end) On a real UNIX like illumos and SmartOS, EXAMPLES are mandatory; I’ve no idea why people believe they may be optional, as they are one of the biggest reasons why someone would call up a manual page. It’s a manual.

pletnes 9y ago

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.

microcolonel 9y ago

> not even as a reference How are you supposed to write reference documentation without a section for describing the options which can be referred to by option name? > The examples should have come first, in the synopsis. Type with me: / E X A <return>. If anything, perhaps the first manual a man user should read is the manual for their default pager, usually LESS(1). There are good and bad manpages, but I don't see how the format is truly deficient. Some very complex commands have separate sections for the most and least common options (or groups of related options, if there are subcommands or similar).

unixhero 9y ago

I agree. An an author of several command line tools I would never document it's usage in the way the classical man pages are structured. They are in times of dire need, frankly, unhelpful. I ALWAYS have to Google it, since the man page gave me nothing.

knolan 9y ago

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 https://uk.mathworks.com/help/symbolic/svd.html

jmfayard 9y ago

Man is like javadocs: useless unless you already know what you are doing, and then usually a wordy paraphrase of the method signature :( Even as a reference manual, man is bad though. If I'm looking for option "-e" of the test command, why can't I do $ man test -e -e file True if file exists (regardless of type). That seems more efficient, more unix-friendly and not too much to ask. I get this is an historical tool that only cares about displaying the output of nroff. We would need a new tool with more empathy ($ woman? )

kleiba 9y ago
De gustibus non est disputandum. I've found javadocs enormously helpful when I was learning Java 20 years ago. But then again, I also like man pages and use them a lot. If I'm looking for option "-e" of the test command, here's what I would do: $ man test and then "/-e". Searching within a document is a commonly required skill in so many situations that I don't even think twice when applying it in man pages. Of course, you could also just define a bash function for the functionality you're after like so: mano() { man "$1" | grep -A1 -- "$2" } and then do $ mano test -e or something along those lines.
- jmfayard 9y ago
  That's full text search, not having directly the argument definition. If you search "-l" in "man ls", it will be only your 8th occurence.
  - kleiba 9y ago
    Sure, you're right, it's not the same thing. I just gave a simple example of something that's close, but I'm not even using a bash function like that myself. If I did, though, I guess the 8th occurrence wouldn't be so bad in my book, since the results can be scanned rather quickly. You could always make your function more clever, e.g.: function mano() { man "$1" | grep -A1 -- "$2\\b" } or function mano() { man "$1" | grep -A1 -- "$2 " } but most probably, you will still run into edge cases that won't work properly. For instance, only one of the two versions above still works with "test -e".

justin66 9y ago

> The examples should have come first, in the synopsis. That is just a terrible idea. First, if what you're putting in the synopsis is not "a brief summary or general survey of something" then the section is misnamed or the content does not belong there. Examples don't belong there. Second, and more importantly, plenty of commands can do enough damage that people ought to read up on what they do before receiving an example. You're giving someone a false sense of confidence if you throw an example at them first thing. That's appropriate enough in some contexts, but not in official documentation for software tools. > The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. The problems you go on to list have nothing to do with the structure, and everything to do with the content contained within that structure. > No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. Since "documentation experts" write documentation this way, it's hard to imagine why you'd assert this.

xtiansimon 9y ago
I share your reactions, with the exception that examples first or last seems irrelevant when using a man page—Sometimes it’s better first because you simply need a reminder how to use the command, and other times you need to read more of the description to catch the warnings before you use the command for the first or infrequent time. But if you follow the General best practice to read the whole of some documentation before you use a command, then this too seems irrelevant. That said, if you’re writing, reviewing, and editing documentation, the traditional structure is hierarchical and consistent—-which is good.

Annatar 9y ago

and maybe Examples at the end) On a real UNIX like illumos and SmartOS, EXAMPLES are mandatory; I’ve no idea why people believe they may be optional, as they are one of the biggest reasons why someone would call up a manual page. It’s a manual.