7 ms·

GNU Parallel - an amazing tool with the most user unfriendly brick-wall-in-your-face documentation imaginable. Shame really - it's great.

by noja 10y ago

flatfilefan 10y ago
To be honest the same can be told about many GNU tools. At least myself I still experience this moment of being totally lost infront of the man screen from time to time. Parallel has a nice tutorial https://www.gnu.org/software/parallel/parallel_tutorial.html https://www.gnu.org/software/parallel/parallel_tutorial.html Have you seen it?
- deleted 10y ago
  [deleted]
- Mahn 10y ago
  I always get the feeling that most man pages are written for people who already know how to use the commands, rather than people new to them. For example, if I already understand how tar works and have a general idea of how to use it, man tar is great to drill down and find specific options and switches that I need or don't remember, but if I have no idea what tar files are or why would I want them, the man page really doesn't help much in explaining things. I guess you could argue this is supposed to be so and man pages are doing their job, since they are documentation and not tutorials, but still.
  - kobeya 10y ago
    Info pages are better for that.
    - ams6110 10y ago
      Info pages should be banished from the face of the earth. https://xkcd.com/912/ https://xkcd.com/912/
      - kobeya 10y ago
        I don't get it. The info pages usually have way more information available, and are proper software manuals with plenty of worked out examples, voluminous descriptive text, and hyperlinks to related resources. Try `info sed` and compare that with the bare breakdown of command line options and basic syntax of `man sed`. I'm not sure what that comic has to do with anything.
        ams6110 10y ago
        Man pages are (in my experience) almost always viewed on a text console or terminal. Info pages work poorly there, and it's just frustrating to be looking for some information in a man page and have to start up some other program with a different UX to complete the task. Man page standards have places for "See also" and "Examples" and that is good enough.
  - peatfreak 10y ago
    > I always get the feeling that most man pages are written for people who already know how to use the commands, rather than people new to them. This is actually true. In some of the early Unix documentation or an interview (I can't remember which), one of the core Unix developers said pretty much this, i.e., that man pages were more like a collection of rough notes to help the developers of the Unix system itself not to forget how the commands should be invoked.
  - guard-of-terra 10y ago
    There was a time when many man pages had healthy EXAMPLES section. It seems less frequent now. And info pages are a disaster. we have bropages for that alas they don't see much activity.
    - ole_tange 10y ago
      Can I ask to to run these and then comment? LESS=+/EXAMPLE: man parallel LESS=+/Reader.s man parallel man parallel_tutorial
      - guard-of-terra 10y ago
        I'm sorry if you got the idea that EXAMPLE section is lacking in parallel manpage. I wasn't checking that, I was ranting on the general state of man pages. I checked ls, curl, wget, mv - none of which had EXAMPLE sections, and that's where I wrote the comment. Didn't even have parallel on my system.
  - ole_tange 10y ago
    The options section is no doubt for people, who know the tool. But the huge section with examples is not. Did you read the "Reader's guide" which is presented before the first option in the man page?
- kevin_thibedeau 10y ago
  Gnu man pages almost universally suck. You're expected to use the info docs or their HTMLified versions.
gravypod 10y ago
The man page isn't too bad. It is better to just look at examples in my case and see what you can find. I do agree it needs some work to be a little more approachable.
- noja 10y ago
  parallel --help is not friendly, and the man page is too comprehensive - really! - most of it belongs in /usr/share/doc The examples are a pain to find - jump to the end (here comes the smack in the face) and see pages of differences to other tools.
  - throwanem 10y ago
    It's a GNU project. It may have a texinfo manual from which the manpage is generated; if so, the info version will have hyperlinks and the like. (But you're probably better off reading the HTML version which should be, as you say, in /usr/share/doc.)
    - moonbug2 10y ago
      No one looks at texinfo docs.
      - lisivka 10y ago
        pinfo is better than info for viewing info pages, but I agree: nobody looks at info pages. It's much easier to google documentation than to navigate to it in info.
    - na85 10y ago
      I've been using Linux since about 1999 and have never looked at a texinfo page. Or, at least, I don't think so, because I don't know what they are or how to access them.
  - ole_tange 10y ago
    The page with differences to other tools will be moved to 'man parallel_aternatives' in next version. It made sense when the section was short, but it has grown so big that it can make it harder to navigate. Thanks for input. (The trick to find the examples: LESS=+/EXAMPLE: man parallel )
hackuser 10y ago
At the risk of sounding obnoxious, people might consider writing better documentation - perhaps in a wiki where they can collaborate on it.
- hinkley 10y ago
  I try to convince my teams to use wiki for the first draft and then export to whatever tool you prefer for delivery versions. Sometimes it works, sometimes it doesn't.
ole_tange 10y ago
A lot of effort has gone into the documentation of GNU Parallel: Intro videos, a one hour tutorial, tons of examples, a man page on the design decisions behind the code, and even a "Reader's guide" in the man-page. Can you be a bit more specific why you believe it is a "brick-wall-in-your-face"? Did you follow the "Reader's guide", which is before even the first option is introduced?
mmstick 10y ago
Should check out the documentation for my Rust implementation of Parallel. Same syntax applies. https://github.com/mmstick/parallel https://github.com/mmstick/parallel
- ole_tange 10y ago
  > Same syntax applies. Except that is not entirely true: For instance according to the author the '{= perl expression =}' will probably never be supported. (Full disclosure: I am the author of GNU Parallel. I fully support building other parallelizing tools, but to avoid user confusion, I would recommend calling them something other than 'parallel' if they are not actually compatible with GNU Parallel).

GNU Parallel - an amazing tool with the most user unfriendly brick-wall-in-your-face documentation imaginable. Shame really - it's great.

by noja 10y ago

GNU Parallel - an amazing tool with the most user unfriendly brick-wall-in-your-face documentation imaginable. Shame really - it's great.

flatfilefan 10y ago

To be honest the same can be told about many GNU tools. At least myself I still experience this moment of being totally lost infront of the man screen from time to time. Parallel has a nice tutorial https://www.gnu.org/software/parallel/parallel_tutorial.html https://www.gnu.org/software/parallel/parallel_tutorial.html Have you seen it?

deleted 10y ago
[deleted]
Mahn 10y ago
I always get the feeling that most man pages are written for people who already know how to use the commands, rather than people new to them. For example, if I already understand how tar works and have a general idea of how to use it, man tar is great to drill down and find specific options and switches that I need or don't remember, but if I have no idea what tar files are or why would I want them, the man page really doesn't help much in explaining things. I guess you could argue this is supposed to be so and man pages are doing their job, since they are documentation and not tutorials, but still.
- kobeya 10y ago
  Info pages are better for that.
  - ams6110 10y ago
    Info pages should be banished from the face of the earth. https://xkcd.com/912/ https://xkcd.com/912/
    - kobeya 10y ago
      I don't get it. The info pages usually have way more information available, and are proper software manuals with plenty of worked out examples, voluminous descriptive text, and hyperlinks to related resources. Try `info sed` and compare that with the bare breakdown of command line options and basic syntax of `man sed`. I'm not sure what that comic has to do with anything.
      - ams6110 10y ago
        Man pages are (in my experience) almost always viewed on a text console or terminal. Info pages work poorly there, and it's just frustrating to be looking for some information in a man page and have to start up some other program with a different UX to complete the task. Man page standards have places for "See also" and "Examples" and that is good enough.
- peatfreak 10y ago
  > I always get the feeling that most man pages are written for people who already know how to use the commands, rather than people new to them. This is actually true. In some of the early Unix documentation or an interview (I can't remember which), one of the core Unix developers said pretty much this, i.e., that man pages were more like a collection of rough notes to help the developers of the Unix system itself not to forget how the commands should be invoked.
- guard-of-terra 10y ago
  There was a time when many man pages had healthy EXAMPLES section. It seems less frequent now. And info pages are a disaster. we have bropages for that alas they don't see much activity.
  - ole_tange 10y ago
    Can I ask to to run these and then comment? LESS=+/EXAMPLE: man parallel LESS=+/Reader.s man parallel man parallel_tutorial
    - guard-of-terra 10y ago
      I'm sorry if you got the idea that EXAMPLE section is lacking in parallel manpage. I wasn't checking that, I was ranting on the general state of man pages. I checked ls, curl, wget, mv - none of which had EXAMPLE sections, and that's where I wrote the comment. Didn't even have parallel on my system.
- ole_tange 10y ago
  The options section is no doubt for people, who know the tool. But the huge section with examples is not. Did you read the "Reader's guide" which is presented before the first option in the man page?
kevin_thibedeau 10y ago
Gnu man pages almost universally suck. You're expected to use the info docs or their HTMLified versions.

gravypod 10y ago

The man page isn't too bad. It is better to just look at examples in my case and see what you can find. I do agree it needs some work to be a little more approachable.

noja 10y ago
parallel --help is not friendly, and the man page is too comprehensive - really! - most of it belongs in /usr/share/doc The examples are a pain to find - jump to the end (here comes the smack in the face) and see pages of differences to other tools.
- throwanem 10y ago
  It's a GNU project. It may have a texinfo manual from which the manpage is generated; if so, the info version will have hyperlinks and the like. (But you're probably better off reading the HTML version which should be, as you say, in /usr/share/doc.)
  - moonbug2 10y ago
    No one looks at texinfo docs.
    - lisivka 10y ago
      pinfo is better than info for viewing info pages, but I agree: nobody looks at info pages. It's much easier to google documentation than to navigate to it in info.
  - na85 10y ago
    I've been using Linux since about 1999 and have never looked at a texinfo page. Or, at least, I don't think so, because I don't know what they are or how to access them.
- ole_tange 10y ago
  The page with differences to other tools will be moved to 'man parallel_aternatives' in next version. It made sense when the section was short, but it has grown so big that it can make it harder to navigate. Thanks for input. (The trick to find the examples: LESS=+/EXAMPLE: man parallel )

hackuser 10y ago

At the risk of sounding obnoxious, people might consider writing better documentation - perhaps in a wiki where they can collaborate on it.

hinkley 10y ago
I try to convince my teams to use wiki for the first draft and then export to whatever tool you prefer for delivery versions. Sometimes it works, sometimes it doesn't.

ole_tange 10y ago

A lot of effort has gone into the documentation of GNU Parallel: Intro videos, a one hour tutorial, tons of examples, a man page on the design decisions behind the code, and even a "Reader's guide" in the man-page. Can you be a bit more specific why you believe it is a "brick-wall-in-your-face"? Did you follow the "Reader's guide", which is before even the first option is introduced?

mmstick 10y ago

Should check out the documentation for my Rust implementation of Parallel. Same syntax applies. https://github.com/mmstick/parallel https://github.com/mmstick/parallel

ole_tange 10y ago
> Same syntax applies. Except that is not entirely true: For instance according to the author the '{= perl expression =}' will probably never be supported. (Full disclosure: I am the author of GNU Parallel. I fully support building other parallelizing tools, but to avoid user confusion, I would recommend calling them something other than 'parallel' if they are not actually compatible with GNU Parallel).