[SciPy-dev] Namespaces in documentation

John Hunter jdh2358@gmail....
Tue Jun 3 13:40:27 CDT 2008


On Tue, Jun 3, 2008 at 12:48 PM, Bruce Southey <bsouthey@gmail.com> wrote:

> That is largely irrelevant because documentation is orientated to people
> not working on the code as those that work on the code already know the
> code. An important aspect of documentation is to reach out to people who
> are don't have the depth of the knowledge so they can use NumPy in any
> way that they want to (in accordance to the licensing).

There is some truth to this: seasoned veterans often do not make good
documentation writers because they forget how much they are assuming.
But it is not irrelevant: part of the goal of documentation is to help
new users acquire the depth of hard won knowledge the experts have,
and many of the experts here have learned that the recommended coding
practice solves many common problems and strikes the right balance
between usability and readability.    So their view is not irrelevant
-- they are trying to help users avoid mistakes they have made in
their own code and adopt coding practices that are realistic, healthy,
and scalable.

In all the original pylab examples, I wrote at the top of every example:

   from pylab import *

then I could write nice little scripts like

   x = randn(10000)
   hist(x, 100)
   title('a normal distribution')

I did this to reach out to the large community of users who are
familiar with matlab (or other command languages for numerics) since
the resultant scripts were small, easy and unencumbered with a
syntactic cruft.  I got a lot of flack for it at the time and no
longer promote this usage; I find that students respond favorably to
the clarity of namespaces.

Most of the developers here who are advocating this import scheme are
not so far removed from the needs of the user community.  Most of us
are not professional programmers -- we are trained as scientists.
Many of us have been working a long time to write code that is usable
by students and scientists who are not programmers, and have taught
scientific computing courses in python on many occassions, where we
get to see first hand the confusion and struggles that students and
new users trying to use this suite encounter.   In fact, my opionions
on the subject have come directly from my experiences teaching python,
ipython, numpy, scipy, matplotlib and enthought in these seminars.

JDH


More information about the Scipy-dev mailing list