Python documentation too difficult for beginners

L

Lawrence D'Oliveiro

In message
rustom said:
The printed python docs come to several thousand pages. Do we want them
to be 1 manpage? a hundred? a thousand?

Perl managed to condense a lot of useful information into a handful of man
pages.
 
M

Mark Wooding

Tim Harig said:
When the GNU folk decided to clone *nix they decided that they knew
better and simply decided to create their own interfaces.

This isn't the case. Actually Info has a long history prior to GNU: it
was the way that the documentation was presented at the MIT AI lab. In
fact, Info was used rather like a modern wiki. The operating system
they used, called ITS, didn't have a concept of file permissions, and
users were encouraged to improve documentation (and programs). The
original Info viewer was implemented in Emacs (which also originated in
ITS, years before GNU).

Texinfo was a GNU innovation: the idea that you could build both the
Info document and a nice printable manual from a single source was
novel, as was the application to Unix. But, since Stallman was
documenting large software systems like Emacs and GCC, it doesn't seem
unreasonable to provide manuals which are somewhat more discursive and
leisurely than traditional Unix manpages. I have a printed copy of the
GNU Emacs 18 manual (from 1987): it's almost 300 pages long. The modern
manual for Emacs 23 is several /times/ larger than this. Man pages
don't scale that well.

I do agree it's annoying that the official coreutils documentation is in
Texinfo.
Actually, the left arrow key does not work at all intuitively. One
would expect that it should go back to the previous page as it would
in lynx, etc. It does not.

It moves the cursor so you can hit links. The l key takes you back
through your recent viewing history -- and has done for thirty years.
By tradition 'n' and 'p' are broken for scrolling in a page. 'b' is
often used in place of p but that seems to take one back to the top of
the page.

Space and backspace are an older tradition.
The s key for a search is another example that has already been
discussed.

I find C-s more useful in Info, because it searches interactively. I
frequently get muddled when I try to search in `modern' programs like
web browsers, because they've gratuitously made C-s try to save the page
(something one hardly ever wants to do) rather than search. (Finding is
different: finding is what happens at the end of a /successful/ search.
So C-f is poorly chosen.)

-- [mdw]
 
N

News123

However, there is a Python wiki. It doesn't get anywhere near as much
love as it deserves, and (I think) the consensus was that the official
Python docs should stay official, but link to the wiki for user-
contributed content. This hasn't happened yet.

http://wiki.python.org/moin/


That sounds like an excellent idea.
I often would have appreciated more examples or discussions about a
given module/class/function without having to fall back to Google.


It might be a good compromise:

clearly separating official doc and examples, but accepting, that the
doc is often insufficient without digging into the sources or searching
for more xamples.

The more one uses python, the easier it becomes to find what one looks for.

My first Impression about Python however was:
- the basic language is rather easy to learn
- the library documentation was more difficult to understand than the
one for PHP or for Perl.


Frankly, I think that the best thing you could do is start a fork of the
docs and see if you get any interest from people. If you do, then you can
go back to python-dev with proof that there is a genuine popular desire
for more structured, PHP-style documentation.

I'd prefer crosslinking the doc with something, that's easier for
beginners of for people who never used a given library before.
 
T

Tim Harig

This isn't the case. Actually Info has a long history prior to GNU: it
was the way that the documentation was presented at the MIT AI lab. In
fact, Info was used rather like a modern wiki. The operating system
they used, called ITS, didn't have a concept of file permissions, and
users were encouraged to improve documentation (and programs). The
original Info viewer was implemented in Emacs (which also originated in
ITS, years before GNU).

I was aware of Emacs history. I was not aware that info actually dated
all the way back to ITS. In retrospect, Stallman might have done better
cloning ITS as that seems to have been what he wanted to do anyway. I
suppose that Emacs is basically just an ITS lookalike shell for making *nix
systems look like ITS.

Coming from a *nix background and not being an Emacs users, I prefer the
traditional *nix methods.
documenting large software systems like Emacs and GCC, it doesn't seem
unreasonable to provide manuals which are somewhat more discursive and
leisurely than traditional Unix manpages. I have a printed copy of the
GNU Emacs 18 manual (from 1987): it's almost 300 pages long. The modern
manual for Emacs 23 is several /times/ larger than this. Man pages
don't scale that well.

Actually, they are capable of the same scalability. I would suggest that
you read the ncurses man pages as they are displayed by pinfo. The man
page links to other man pages that are organized by functionality in the
same kind of tree organization that is used for (text)info pages.
It moves the cursor so you can hit links. The l key takes you back
through your recent viewing history -- and has done for thirty years.

As I said, that is probably intuitive for Emacs users; but, not all *nix
users are Emacs users. To those of us that are not, the info interface
seems quite alien.
Space and backspace are an older tradition.

Right, and in info with the default key bindings, backspace takes me to the
command help. I would have expected it to either scroll up the page or
take me to the previously visited node.
I find C-s more useful in Info, because it searches interactively. I
frequently get muddled when I try to search in `modern' programs like
web browsers, because they've gratuitously made C-s try to save the page
(something one hardly ever wants to do) rather than search. (Finding is
different: finding is what happens at the end of a /successful/ search.
So C-f is poorly chosen.)

/ is even more intiuitive yet, it works in more, it works in less, it works
in vi, and it even works in firefox.
 
M

Mark Wooding

Tim Harig said:
Right, and in info with the default key bindings, backspace takes me
to the command help. I would have expected it to either scroll up the
page or take me to the previously visited node.

Sounds like your terminal is misconfigured. Backspace should produce
^?, not ^H. (Delete should produce some awful escape sequence.)

-- [mdw]
 
T

Tim Harig

As has been noted before, there is no intuitive interface except the
nipple. Everything else is not intuitive, but must be learned.

What exactly is so intuitive about being slapped in the face followed by
being slapped with a lawsuit?
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,744
Messages
2,569,484
Members
44,903
Latest member
orderPeak8CBDGummies

Latest Threads

Top