What confuses the newbies: An unscientific study

[phil hunt]

On Sat, 21 Jul 2001 04:00:57 GMT, Nick Mathewson <9nick9m at alum.mit.edu> wrote:
>
>1. NOT KNOWING WHERE MODULE DOCUMENTATION IS.
>
>   A good fifteen or so people asked questions of the form, "How do
>   I...", "Is there a module that can...", etc.  All of these
>   questions were answered with references to the library reference,
>   or to the Vaults.
>
>   Perhaps when the Python Cookbook is more compiled, these things
>   will be easier.
>
>   BTW, the most common requests were satisfied by: (in no particular
>   order) XML/SGML parsing, windowing toolkits, popen, timeoutsocket,
>   and stringio.  Other requests turned out to be for chr and popen2.
>  
> * A related kind of confusion: in 4 or so of these cases, users knew
>   about a function that did _almost_ the right thing, and [instead
>   of looking for the function they _really_ wanted] they searched
>   for a way to make the almost-right function do the right thing.

An example that happened to me recently was os.system() doing almost
but not quite the same thing as commands.getstatusoutput().

The Python documentation is HTML (at least, LaTeX processed into HTML).
Would it be possible for the descriptions of these two functions
to have hypertext links to each other, since they are clearly related?

In general, I'd say the documenation for the standard library could
do with more examples.

Also I'd be nice if there wqas a function like getstatusoutput() that
returned the stdout output as a separate string to the stderr output.
Then you could for example raise an exception if the return value wasn't
0, and use the stderr text as an argument to the exception.

>5. OTHER ISSUES:
>
>   2 people expected strings to act mutably:
>     1 expected string.strip to have side effects
>     1 expected string slices to be assignable

This coulkd be fixed by improving the documentation

>   2 people had issues with aliasing lists
>     1 tried to do a lst.remove within a loop over lst
>     1 expected [[...]]*6 to perform a deep copy

ditto
 
>   2 people were confused about fp.
>     1 person thought that int/int should yield a float

I thiunk it should yield a fraction so:
   print ((1/3)*(1/3))*4 

would output:
   4/9.

But I expect that's just me.

>     1 person didn't know that fp was inexact

Perhaps Python could do with a decimal type like C# has?


-- 
#===== Philip Hunt == philh at comuno.freeserve.co.uk ======#
 Herbivore: effort-free public key email encryption. See:
<http://www.vision25.demon.co.uk/oss/herbivore/intro.html>
          *** herbrip software now released ***