On May 10, 2014, at 6:10 PM, Nick Coghlan <ncogh...@gmail.com> wrote:
> > On 11 May 2014 07:37, "Raymond Hettinger" <raymond.hettin...@gmail.com> wrote: > > > > > > On May 10, 2014, at 2:18 PM, Alex Gaynor <alex.gay...@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. > I completely agree with Alex, Antoine, and Nick here. I’m both an experienced Python programmer and someone who is generally aware of the security implications of various parts of software. However I appreciate when I look at documentation that explicitly calls out the ways I might screw it up, especially in a security sensitive context, but I appreciate it any context really. ----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
signature.asc
Description: Message signed with OpenPGP using GPGMail
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
