[SciPy-User] Documentation

The Helmbolds helmrp@yahoo....
Sun Jul 22 18:11:44 CDT 2012


Ralf,
 
Thanks for the response. At the moment I'm interested in editing/revising the docstrings and SciPy Guide sections for the optimize package, as I find them confusing and misleading for newcomers. After getting some more detailed experience with the optimize package, I expect I'd like to try my hand at drafting some tutorials for it. 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.

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. 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.
 
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?
 
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.

The Helmbolds
2645 E Southern Ave A241
Tempe AZ 85282
Email: helmrp@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@googlemail.com>
>To: The Helmbolds <helmrp@yahoo.com>; SciPy Users List <scipy-user@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@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)   
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-user/attachments/20120722/913fbf5e/attachment-0001.html 


More information about the SciPy-User mailing list