[SciPy-dev] 2-review system on doc wiki

Joe Harrington jh@physics.ucf....
Mon Feb 15 12:34:44 CST 2010


On Sun, Feb 14, 2010 at 11:56 AM, <josef.pktd@gmail.com> wrote:

> Most scipy subpackages have tutorials, and if a user needs an
> introduction then it is necessary to read the tutorial.

Agreed that a lot can go into the tutorials; we need clearer
guidelines on what should go in tutorial vs. function docstrings.
Perhaps more importantly, we need to educate people about the
existence of these tutorials, perhaps in the see-also to each routine,
or at least in the module docstrings.

> And for a basic introduction Wikipedia is
> more informative than a docstring can be.

Agreed that it is our job to inform about what the routines are and
how to use them to do likely tasks, not to teach people the math
behind them.  But, it is pretty standard to include enough of that
math (such as a formula) to demonstrate what the routine does.  This
is particuarly important where there is more than one way it's
defined, such as the normalization for Fourier transforms (does it go
on the forward transform, the inverse, or split between them).

--jh--



More information about the SciPy-Dev mailing list