[SciPy-User] Documentation

Sun Jul 22 19:38:34 EDT 2012

On Sun, Jul 22, 2012 at 6:11 PM, The Helmbolds <helmrp at yahoo.com> wrote:

<snip>

>  I noticed that the link to "Cookbook" just goes to a blank page, so if
> given some guidance on what you envision for that area, I might try
> drafting up something for it.
>

The "Cookbook" page might have been a little slow to appear.  Try it again.

> If I'm to have a go at the optimize package, it would be important to
> have an expert in optimization theory and practice back me up. I can handle
> the style and understand the basics well enough to make a good start, but
> it would be best for all concerned to have someone else checking the
> factual accuracy of the text. For example, I'd expect the expert to rap
> my knuckles if I said something as inaccurate as "a vanishing gradient
> always indicates a minimum", and to remind me to consider stationary points
> and constraint functions.
>

Agreed!

> Moreover, I do not have access to the underlying C algorithms (I'm using
> Windows 7 operating system), nor to the publications referenced (I have no
> access to any college or university library). Hence, I may not be
> interpreting everything correctly.
>
> Expect me to be slow but persistent. Also expect me to be very sensitive
> to imprecise expressions.
>

A critical editorial eye on the documentation is quite welcome.  Thanks for
offering to help.

> Some examples of this sensitivity are the following, from the "SciPy
> Reference Guide, Release 0.11.0.dev-659017f":
>
> Re: Section 1.5.1 et seq: This section refers to "multivariate scalar
> functions". I suppose that "multivariate real-valued functions" is really
> what is intended. And similarly for "scalar univariate functions".
> Physicists and mathematicians often consider complex numbers and other
> things as "scalars".
>     Even though mentioned within the Nelder-Mead section, I still think
> it's not the best practice to refer to the "simplex algorithm" without some
> qualification to remind the reader that Dantzig's algorithm is not the
> intended reference.
>     Text refers to "interior derivatives", and I don't think that is
> widely understood terminology. Certainly I don't know if what is intended
> is any different from the ordinary partial derivatives.
>     Docstrings refer to 'jac'. I haven't looked into this in great detail,
> but it seems likely that this actually refers to the gradient rather than
> the Jacobian determinant. But could it be that this terminology is what is
> used in the underlying C routines?
>

'jac' refers to the Jacobian matrix (
http://en.wikipedia.org/wiki/Jacobian_matrix_and_determinant).

>
> Re: Sections 1.12.1 and 4.7.2: These refer the reader to the "numpy
> manual", or to "the reference manual" for further details. I cannot  find
> any such "manuals" mentioned in the SciPy document pages on the web.
>
> I know this sounds critical, especially from someone new. I feel
> vulnerable to the counter-criticism "so where were you when the page was
> blank!?" However, believe me when I say that I have great sympathy for the
> folks who wrote the code and the documentation. Neither are easy, and to do
> both is extremely difficult! But perhaps I can help things along if I do my
> little bit.
>
>

Any help is appreciated.  Please dive in!

Warren

The Helmbolds
> 2645 E Southern Ave A241
> Tempe AZ 85282
> Email: helmrp at yahoo.com
> VOX: 480-831-3611
> CELL Igor: 480-438-3918
> CELL Alf: 602-568-6948 (but not often turned on)
>
>    *From:* Ralf Gommers <ralf.gommers at googlemail.com>
> *To:* The Helmbolds <helmrp at yahoo.com>; SciPy Users List <
> scipy-user at scipy.org>
> *Sent:* Sunday, July 22, 2012 12:33 PM
> *Subject:* Re: [SciPy-User] Documentation
>
> On Sun, Jul 22, 2012 at 1:09 AM, The Helmbolds <helmrp at yahoo.com> wrote:
>
> I'm interested in contributing to SciPy's documentation, but am uncertain
> who my point of contact should be.
> Please enlighten me.
>
>
> That's great, welcome! As for a point of contact, usually the best idea is
> posting to this list, in case of any questions or issues you need feedback
> on or help with.
>
> Do you have an interest in a certain module, or preference for improving
> docstrings vs. contributing tutorial-style docs? Once we know that we could
> give you some more specific ideas of things that need work.
>
> As for the way to contribute, there are two for documentation:
> - we have a wiki-style editor where you can edit all docs:
> http://docs.scipy.org/scipy/Milestones/. There's some info for getting
> started at http://docs.scipy.org/numpy/Front%20Page/. You'll need to ask
> for edit permissions on this list after registering a username there.
> - you can send pull requests with changes on Github. You can find useful
> info related to that at
> https://github.com/scipy/scipy/blob/master/HACKING.rst.txt
>
> Cheers,
> Ralf
>
> (Some stuff removed to avoid unneceesary duplication)
>
>
> _______________________________________________
> SciPy-User mailing list
> SciPy-User at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-user
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.scipy.org/pipermail/scipy-user/attachments/20120722/2f074257/attachment.html>