[SciPy-Dev] Contributing to the Documentation

[Cera, Tim]

On Fri, Aug 2, 2013 at 11:33 AM, Juan Luis Cano <juanlu001 at gmail.com> wrote:

>  On 08/01/2013 11:29 PM, Ralf Gommers wrote:
>
> Not a huge amount, but still regular edits (thanks mainly to Tim Cera)
> adding up to 1000s of words for every release. The wiki also has some
> advantages if you'd want to edit larger amounts of docs, like a system to
> indicate if a docstring is draft / for review / reviewed, and the option to
> render a page (helps to fix formatting issues). But yes, overall I'd still
> prefer PRs over wiki edits.
>
>
I got used to the editor.  And I am now going to type a bit of heresy: I
use git, but I really don't like it.  The complexity/benefit ratio is too
high for my poor brain.

There is an overlooked advantage to the editor in that when edits are
previewed there are several tests that validate the docstring you are
working on.  Those tests could be made part of the test suite (and
expanded), but currently they are only in the on-line editor.

Also, there are bug fixes and additional features in the development
version of pydocweb that would be nice to see in the on-line doc editor.
 Actually, these might have been implemented, apologies if anyone has
already done this - haven't been on in awhile.

And in terms of editing the docstrings, there are many discussions,
comments, ...etc. about different format issues that are scattered across
the e-mail list, the discussion section of the on-line editor - but very
few decisions.  Really would be helpful to codify all of these discussions
into decisions, write them down, AND implement them as tests.

Kindest regards,
Tim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20130802/076bafa9/attachment.html>