On Thu, Dec 1, 2011 at 5:36 PM, Nick Coghlan <ncogh...@gmail.com> wrote: > On Thu, Dec 1, 2011 at 5:15 PM, Glyph <gl...@twistedmatrix.com> wrote: >> I think both of these documents point to a need for a recommended idiom for >> discussing security, or at least common antipatterns, within the Python >> documentation. I like the IETF's "security considerations" section, because >> it separates things off into a section that can be referred to later, once >> the developer has had an opportunity to grasp the basics. Any section with >> security implications can easily say "please refer to the 'security >> considerations' section for important information on how to avoid common >> mistakes" without turning into a big security digression on its own. > > I like that approach - one of the problems with online docs is the > fact people don't read them in order, hence the proliferation of > warnings for the subprocess module. A clear "Security Considerations" > section with appropriate cross links would allow us to be clear and > explicit about common problems without littering the docs with red > warning boxes for security issues that are inherent in a particular > task rather than being a Python-specific problem.
I created http://bugs.python.org/issue13515 to propose a specific documentation style guide adopt along these lines (expanded a bit to cover other cross-cutting concerns like the pipe buffer blocking I/O problem in subprocess). Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
