undefined | Better HN

0 pointsjhallenworld10y ago0 comments

One issue is the problem of indirect documentation, and it comes down to this one line: "import sys, os, subprocess, glob".

How do you find which module you need? Search on the web may be the best answer. In shell at least you have "man -k".

Once I know the module, how do I get its documentation? Here at least there is an answer: import glob; help(glob);

But how good is this documentation? If I do it I get:

    glob(pathname)
    Return a list of paths matching a pathname pattern.
    
    The pattern may contain simple shell-style wildcards a la fnmatch.

Already python is telling me that the "man" documentation is going to be better :-).

0 comments

viraptor10y ago

> How do you find which module you need? Search on the web may be the best answer.

Experience, stdlib reference, web searches. Same as with bash.

> In shell at least you have "man -k".

I really disagree here. Since you took `glob` as an example, how do you get to the explanation of `for test in *.in`? Go on, try that with "man -k".

> Already python is telling me that the "man" documentation is going to be better

I'm not trying to say python is good here (well, the stdlib documentation on the web is actually pretty good, it's just not easily available from the console). But the idea that bash/man is more discoverable is just wrong... You can find the glob under "Pattern Matching" section which is all right, but you need to understand most of the expansion mechanism of shell to know it applies to "for". Then again "for" itself has a definition that belongs more to a CS material, than to a usage guide.

adrusi10y ago

Since you took `glob` as an example, how do you get to the explanation of `for test in .in`?*

`man -k wildcard` points to `man 3am fnmatch` which points to `man 3 fnmatch`. Now the process for python and shell converge, and I still have to know to look at the "See Also" section of the manpage to find `man 7 glob` which finally gives me useful information.

The python workflow involved one fewer discrete step, but the user would have to know both help() in the python REPL and how to navigate man pages, while for shell scripts the user only needed to know how to navigate man pages.

I do very much agree with you here. Man pages are not very accessible. Some man pages (most that I work with, but I understand that's not everyone's experience) are very good, complete, and understandable. I'd be comfortable saying that python's and the shell's documentation features are roughly equally usefule ± some small amount.

jhallenworldOP10y ago

Well I agree that glob was not the best example. For sure there are things you have to learn about shell scripting as well.. one of them is if "man for" doesn't work, try "help for" or "man bash". In fact there is no good reason for this and it should be improved. (not to mention that you already had to know what *.in does, but you could argue that this is fundamental shell syntax: man bash / pattern matching).

j / k navigate · click thread line to collapse