[SciPy-Dev] SciPy docs: volunteers needed now!

[Bruce Southey]

On Sat, Jul 3, 2010 at 11:34 AM, Ralf Gommers
<ralf.gommers at googlemail.com> wrote:
>
>
> On Sun, Jul 4, 2010 at 12:13 AM, Bruce Southey <bsouthey at gmail.com> wrote:
>>
>> On Sat, Jul 3, 2010 at 10:31 AM, David Goldsmith
>> <d.l.goldsmith at gmail.com> wrote:
>> > On Sat, Jul 3, 2010 at 7:24 AM, Benjamin Root <ben.root at ou.edu> wrote:
>> >>
>> >> Joshua,
>> >>
>> >> In addition to the very technical writing for individual functions, we
>> >> also need documentation that is accessible to newcomers.  Many modules
>> >> do
>> >> not implement any functions themselves, but act as a grouping module
>> >> (for
>> >> example, scipy.io).  These modules could definitely use good,
>> >> up-to-date,
>> >> summary narratives.  Even some modules further down the stack can still
>> >> benefit from good summaries.
>>
>> What would really benefit is a solid example for different types.
>> There are so many inconsistent styles in the numpy documentation - I
>> know I wrote some. You can always see that when there are different
>> definitions (when present) for input that are array-like. There should
>> be one single definition for these common input and output that should
>> be immutable by the writer and should automatically appear.
>
> That would be nice but I don't see how that's technically feasible. To see
> whether the input is ndarray or array_like you just have to look at the
> code. And you'll always end up with some minor inconsistencies with many
> writers, but that's what the review/proof stages are for.
>>
>> >>
>> >> To everyone, if you do join the documentation efforts to contribute
>> >> little
>> >> bits of writing, it is a common courtesy to notify any others who might
>> >> also
>> >> be working on a particular document.  The current system does not
>> >> automatically notify authors of any changes, so it is hard to know if
>> >> any
>> >> changes have been made.  General rule of thumb is to notify authors who
>> >> have
>> >> made changes to the doc within the last 3 months (I believe).
>> >
>> > Actually, all you have to do (have used in both senses of the word,
>> > i.e.,
>> > are "required" to do and all that is necessary to do) is click on the
>> > log
>> > link when viewing a docstring in the Wiki, note the person who worked on
>> > it
>> > last, how long ago that was, and then as Ben says, if it was in the last
>> > three months, give or take, contact them and ask them if it would be ok
>> > if
>> > you worked on it.
>>
>> And where is the email or notification button? The more loops to jump
>> through the less people will jump.
>
> Good point.
>>
>> Where do you see the changes made? It should be a diff.
>
> Under Log you have access to all diffs for a docstring.

(Using the word 'diff' was perhaps too limiting - probably more like
track changes in word processors is more appropriate terminology.)
Thanks for pointing that out because I had to search a few examples to
find an example. Otherwise all you get is a 'diff to svn'.
An example is:
http://docs.scipy.org/scipy/docs/scipy.stats.distributions.rv_continuous/log/

Yet you can not tell what was changed and why beyond a trivial comment
(that is often not very correct). There is no link to the discussion
so you do not know what version the discussion applies to.


>>
>> Why does the second person have greater authority to override the
>> original author?
>> Why should I have to go back and check that the later revisions are
>> correct?
>>
> If the first author brings a docstring to "needs review" status there's no
> need for a second author to work on it. If it's still in "being written", it
> wasn't finished in the first place. And later edits possibly overwriting
> earlier ones is just the nature of wikis.
>
>
> Cheers,
> Ralf



Bruce