[docs] How to volunteer?

[Zachary Ware]

Hi Fran,

On Mon, Jan 13, 2014 at 12:13 PM, Fran Bull <fran.bull at gmail.com> wrote:
> Hello!
>
> I would like to help contribute to the Python docs. Are you accepting
> volunteers?

Always!

> This page http://docs.python.org/3.2/about.html says
> 'Development of the documentation and its toolchain takes place on the
> docs at python.org mailing list. We’re always looking for volunteers wanting to
> help with the docs, so feel free to send a mail there!'

Those directions are somewhat misleading.  Everything stated there is
true (and your mails here are certainly welcome), but development
really just happens on the bug tracker.

> For example I would propose fixes for this bug
> http://bugs.python.org/issue20237 like this:

The best course of action is to sign up for a tracker account and add
a message (and/or attach a patch) to that issue.  You may want to take
a look through the devguide (http://docs.python.org/devguide), it will
help you get set up and ready to create a patch.

> The paragraph in question reads:
>
> 'defusedxml is a pure Python package with modified subclasses of all stdlib
> XML parsers that prevent any potentially malicious operation. The courses of
> action are recommended for any server code that parses untrusted XML data.
> The package also ships with example exploits and an extended documentation
> on more XML exploits like xpath injection.'
>
> The complaint is:
>
> '"The courses of action are recommended for any server code that parses
> untrusted XML data."
>
> What this sentence means?
> What "The courses" is?'
>
> It seems that the original author was either trying to say that:
>
> a) The courses of action that defusedxml implements are those recommended
> for any server code that parses untrusted XML data.
> or
> b) Using defused XML is recommended for any server code that parses
> untrusted XML data.
>
> I think b) is more likely. I'd choose a less passive form like:
>
> 'You should use defusedxml for any server code that parses untrusted XML
> data.'
>
> although I would imagine there's a style guide that would inform that.

There is a chapter in the devguide devoted to documentation and
documentation fixes.

> I would also restructure the paragraph to make this sentence the first, to
> emphasize it. Also there is an extraneous 'an' in the last sentence. So my
> proposed fixed paragraph would be:
>
> 'You should use defusedxml for any server code that parses untrusted XML
> data. defusedxml is a pure Python package with modified subclasses of all
> stdlib XML parsers that prevent any potentially malicious operation. The
> package also ships with example exploits and extended documentation on more
> XML exploits like xpath injection.'

Everything above is a good basis for a message to add to the tracker issue.

> I don't have a lot of time, but I would like to help when I can. Let me know
> if and how.

Your contributions are certainly welcome!  I hope I've been of some
help in pointing you the right direction.  If you have more questions,
feel free to send them here (docs at python.org).  You may also be
interested in the core-mentorship mailing list, which is intended to
be a friendly place to get answers to any and all questions pertaining
to the development of Python (including its documentation) with
non-public archives.

Welcome to Python!

--
Zach