[Python-Dev] [Python-checkins] cpython: Remove the redundant and poorly worded warning message.

[Nick Coghlan]

On 11 May 2014 07:37, "Raymond Hettinger" <raymond.hettinger at gmail.com>
wrote:
>
>
> On May 10, 2014, at 2:18 PM, Alex Gaynor <alex.gaynor at gmail.com> wrote:
>
>> I think this change is a considerable usability regression for the
documentation. Right now the warnings about CSPRNGs are hidden in the
introductory paragraph, which users are likely to skip
>
>
> In the past couple of years, we've grown an unfortunate tendency
> to fill the docs with big warning boxes (the subprocess docs are
> an example of implicitly communicating that the module is dangerous
> and unusable).
>
> The preferred form of documentation is to be affirmatively worded,
> telling how to use a tool correctly and what its known limitations are.
> We save the warnings for cases of actual danger where otherwise
> well informed users get tripped-up.
>
> Tim Peters used to be around to articulate the principle that we don't
write
> the docs with the assumption that the users are less bright than we are
> or that they can't read.

That assumption has changed somewhat, as many users are now getting their
education in programming (and how computers work in general) from
introductory community workshops and the Python documentation.

This means that writing our docs based on the assumption that the reader is
already going to be a professional programmer is no longer adequate. This
is especially essential in security related areas, as even professional
programmers usually aren't sufficiently paranoid about all the ways their
software can be attacked.

As Alex notes, the short term way to eliminate the duplication here is to
keep the security warnings and drop the material from the introductory
paragraph, not go back to expecting readers to have already been alerted to
randomness related cryptographic security issues in some other context.
Readers that are already familiar with the security concerns will hopefully
recognise that they're not a Python specific problem (and may even be
appreciative of our attempts to convey the relevant knowledge to a broader
audience), while readers that aren't yet aware of them may be more likely
to account for them appropriately when writing their software. It's as much
about cultivating a more paranoid more mindset in developers in general as
it is about the contents of the specific security warning.

A "Security Considerations" section in the module documentation can be a
better way to tackle this than trying to jam everything into one warning
box, but there should still be a "Here be dragons" warning early on noting
that random *is* a potentially security sensitive module in a cryptographic
context.

Regards,
Nick.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20140511/c1c29a11/attachment.html>