[Edu-sig] Top 5 All Time Novice Obstacles => #3 Where am I ?

[Jason Cunliffe]

> > Yes. The Python guts are all much more visible here:
> >
> > PYTHON
> > >>> help(os)
>
> Sorry, I'm not sure what you mean (in fact I'm not even sure if that's
> good or bad!)  Can you explain what you mean?

Sorry. {mind-reading-not-included}

My premise is that novices need more overview and quickly, than hackers. Or
rather that hackers know well how to get the help they need ;-) Its the prime
skillset [getting help => learning how to learn]

So for contrast I showed a REBOL example, very crisp and upfront, which includes
docstrings in clean formatted list group. It also does a dictionary search for
similar words. [REBOL's "help" operator has shorter alias "?"]

So in Rebol when you type help for a known word it will deliver just the
docstrings for that word. Very to the point, like Python. But if you feed 'help'
a short fuzzier string, or perhaps example a word  which is a substring of
several  words known to the Rebol interpreter, it will go return all of those..
A more extreme example is to type one letter.

>> ? d    ;returns all the words which contain "d"

>> ? dir  ;returns all the words which contain "dir"

>>  >> ? what-dir
USAGE:
    WHAT-DIR

DESCRIPTION:
     Prints the active directory path
     WHAT-DIR is a function value.

Like searching google there is quickly learned art in know when to widen and
when to narrow the search based on fat returns.

Python has just a massive amount of everything, including help. But is still
dominantly by and for hackers, and brilliant ones too. That's what makes it so
great, but not yet imho well tuned for true beginners as much as it could be.


When you ask python for very specific help it delivers, but that may or may not
be so helpful for the novice. I take your points well about AI and simple things
being hard etc. And common sense is not..

I'll try to illustrate [my comments=A,B,C,etc]:

>>> import os
>>> os.curdir
'.'
>>> help(os.curdir)
problem in  - ValueError: Empty module name
>>> help(os.curdir())
Traceback (most recent call last):
  File "<pyshell#31>", line 1, in ?
    help(os.curdir())
TypeError: 'str' object is not callable


A. help is being very literal here, behaving correctly like the rest Python. But
our student needs help not a lawyer!

>>> os.listdir
<built-in function listdir>
>>> help(os.listdir())
Traceback (most recent call last):
  File "<pyshell#33>", line 1, in ?
    help(os.listdir())
TypeError: listdir() takes exactly 1 argument (0 given)


B. Ok better but help is getting routed to Error. Our student needs help.
>>> help(os.listdir)
Help on built-in function listdir:

listdir(...)
    listdir(path) -> list_of_strings
    Return a list containing the names of the entries in the directory.

            path: path of directory to list

    The list is in arbitrary order.  It does not include the special
    entries '.' and '..' even if they are present in the directory.


C. Aaah yes thank you Python.

Now it turns out that perhaps for our novice the best to get help one of the
'os' module functions in Python is to be __very__ general. KISS rules

>>> help(os)


D. wow. that's throwing the book at them, but it does provide a real overview
within the fist screenful, AND it includes all the help for the functions our
student wanted immediately. Arthur's reply to me implied that suffering until
one has got the syntax down is a healthy part of learning Python. Yes and no.
Let's consider this:

>>> help
Type help() for interactive help, or help(object) for help about object.

>>> help(help)
Help on instance of _Helper:

Type help() for interactive help, or help(object) for help about object.

>>> help()

Welcome to Python 2.2!  This is the online help utility.

If this is your first time using Python, you should definitely check out
the tutorial on the Internet at http://www.python.org/doc/tut/.

Enter the name of any module, keyword, or topic to get help on writing
Python programs and using Python modules.  To quit this help utility and
return to the interpreter, just type "quit".

To get a list of available modules, keywords, or topics, type "modules",
"keywords", or "topics".  Each module also comes with a one-line summary
of what it does; to list the modules whose summaries contain a given word
such as "spam", type "modules spam".

help>


E. OK This is great a help prompt. But why not go straight to help() every time
student uses help and trap the error messages above? Python always gives error
messages. And fine they are for those who know what to make of them. But our
students asked for help and surely does not need more errors. Later on yes,
Error messages = help.

help> listdir
no Python documentation found for 'listdir'


F. Damn! C'mon Python get smart please. Our student is looking for help on
something called listdir. What can't find where it be?

help> os.listdir
Help on built-in function listdir in os:

listdir(...)
    listdir(path) -> list_of_strings
    Return a list containing the names of the entries in the directory.

            path: path of directory to list

    The list is in arbitrary order.  It does not include the special
    entries '.' and '..' even if they are present in the directory.


G. Hooray. This is much better. Now student follows help> prompt's advice:

help> modules

Please wait a moment while I gather a list of all available modules...
[huge list]


H. Python "help()" is rich. But not very smart. Adding a find feature to it
would make it much smarter without needing a heavy AI engine. Finding things is
a large part of the battle and finding similar things is part of *that*. So
giving someone all the modules or all of 'os' is good. And there are powerful
'find' tools in IDLE's menu. But they still tend to assume you know what you
want. And beginners usually don't. If find,help and error functions could be all
brought into sync/context better, I think Python would be much faster on-ramp
for novices. It is a brilliant and friendly language mostly. So please don't
take this for whining.

We need to hear from young novice students and their teachers what helps them
and what hangs them up early on. I am not a teacher and am working from just my
own experiences and imagination.

thanks
./Jason