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

[Joe Harrington]

On Sun, Feb 14, 2010 at 11:56 AM, <josef.pktd at 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--