[docs] How to volunteer?

[Fran Bull]

Hello!

I would like to help contribute to the Python docs. Are you accepting
volunteers? 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!'

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

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

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

Thanks!

Fran
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20140113/ca4a5007/attachment.html>